Fixed #21213 -- Added docs for Django's mailing lists.

Added docs/internals/mailing-lists.txt documenting the use of django's
mailing lists. All references across docs changed to point to this page.

The referencing makes use of substitution because there's no way to make
a :ref: link in a non-inline fashion in Sphinx. It also makes use of
rst_epilog Sphinx conf for making this substitutions across all the
docs.

docs/conf.py

@@ -206,6 +206,14 @@ htmlhelp_basename = 'Djangodoc'
 
 modindex_common_prefix = ["django."]
 
+# Appended to every page
+rst_epilog = """
+.. |django-users| replace:: :ref:`django-users <django-users-mailing-list>`
+.. |django-core-mentorship| replace:: :ref:`django-core-mentorship <django-core-mentorship-mailing-list>`
+.. |django-developers| replace:: :ref:`django-developers <django-developers-mailing-list>`
+.. |django-announce| replace:: :ref:`django-announce <django-announce-mailing-list>`
+.. |django-updates| replace:: :ref:`django-updates <django-updates-mailing-list>`
+"""
 
 # -- Options for LaTeX output --------------------------------------------------
 

docs/faq/help.txt

@@ -5,51 +5,48 @@ How do I do X? Why doesn't Y work? Where can I go to get help?
 --------------------------------------------------------------
 
 If this FAQ doesn't contain an answer to your question, you might want to
-try the `django-users mailing list`_. Feel free to ask any question related
+try the |django-users| mailing list. Feel free to ask any question related
 to installing, using, or debugging Django.
 
 If you prefer IRC, the `#django IRC channel`_ on the Freenode IRC network is an
 active community of helpful individuals who may be able to solve your problem.
 
-.. _`django-users mailing list`: http://groups.google.com/group/django-users
 .. _`#django IRC channel`: irc://irc.freenode.net/django
 
+.. _message-does-not-appear-on-django-users:
+
 Why hasn't my message appeared on django-users?
 -----------------------------------------------
 
-django-users_ has a lot of subscribers. This is good for the community, as
+|django-users| has a lot of subscribers. This is good for the community, as
 it means many people are available to contribute answers to questions.
-Unfortunately, it also means that django-users_ is an attractive target for
+Unfortunately, it also means that |django-users| is an attractive target for
 spammers.
 
-In order to combat the spam problem, when you join the django-users_ mailing
+In order to combat the spam problem, when you join the |django-users| mailing
 list, we manually moderate the first message you send to the list. This means
 that spammers get caught, but it also means that your first question to the
 list might take a little longer to get answered. We apologize for any
 inconvenience that this policy may cause.
 
-.. _django-users: http://groups.google.com/group/django-users
-
 Nobody on django-users answered my question! What should I do?
 --------------------------------------------------------------
 
 Try making your question more specific, or provide a better example of your
 problem.
 
-As with most open-source mailing lists, the folks on django-users_ are
+As with most open-source mailing lists, the folks on |django-users| are
 volunteers. If nobody has answered your question, it may be because nobody
 knows the answer, it may be because nobody can understand the question, or it
 may be that everybody that can help is busy. One thing you might try is to ask
 the question on IRC -- visit the `#django IRC channel`_ on the Freenode IRC
 network.
 
-You might notice we have a second mailing list, called django-developers_ --
+You might notice we have a second mailing list, called |django-developers| --
 but please don't email support questions to this mailing list. This list is
 for discussion of the development of Django itself. Asking a tech support
 question there is considered quite impolite.
 
-.. _django-developers: http://groups.google.com/group/django-developers
-
 I think I've found a bug! What should I do?
 -------------------------------------------
 

docs/index.txt

@@ -17,7 +17,7 @@ Having trouble? We'd like to help!
 * Looking for specific information? Try the :ref:`genindex`, :ref:`modindex` or
   the :doc:`detailed table of contents <contents>`.
 
-* Search for information in the `archives of the django-users mailing list`_, or
+* Search for information in the archives of the |django-users| mailing list, or
   `post a question`_.
 
 * Ask a question in the `#django IRC channel`_, or search the `IRC logs`_ to see
@@ -25,7 +25,7 @@ Having trouble? We'd like to help!
 
 * Report bugs with Django in our `ticket tracker`_.
 
-.. _archives of the django-users mailing list: http://groups.google.com/group/django-users/
+.. _archives: http://groups.google.com/group/django-users/
 .. _post a question: http://groups.google.com/group/django-users/
 .. _#django IRC channel: irc://irc.freenode.net/django
 .. _IRC logs: http://django-irc-logs.com/
@@ -300,7 +300,8 @@ you can contribute:
   :doc:`The release process <internals/release-process>` |
   :doc:`Team of committers <internals/committers>` |
   :doc:`The Django source code repository <internals/git>` |
-  :doc:`Security policies <internals/security>`
+  :doc:`Security policies <internals/security>` |
+  :doc:`Mailing lists <internals/mailing-lists>`
 
 * **Design philosophies:**
   :doc:`Overview <misc/design-philosophies>`

docs/internals/contributing/bugs-and-features.txt

@@ -18,16 +18,16 @@ general points:
   `searching`_ or running `custom queries`_ in the ticket tracker.
 
 * Don't use the ticket system to ask support questions. Use the
-  `django-users`_ list or the `#django`_ IRC channel for that.
+  |django-users| list or the `#django`_ IRC channel for that.
 
 * Don't reopen issues that have been marked "wontfix" by a core developer.
   This mark means that the decision has been made that we can't or won't fix
   this particular issue. If you're not sure why, please ask
-  on `django-developers`_.
+  on |django-developers|.
 
 * Don't use the ticket tracker for lengthy discussions, because they're
   likely to get lost. If a particular ticket is controversial, please move the
-  discussion to `django-developers`_.
+  discussion to |django-developers|.
 
 .. _reporting-bugs:
 
@@ -42,7 +42,7 @@ particular:
 * **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
   be a well-known question.
 
-* **Do** ask on `django-users`_ or `#django`_ *first* if you're not sure if
+* **Do** ask on |django-users| or `#django`_ *first* if you're not sure if
   what you're seeing is a bug.
 
 * **Do** write complete, reproducible, specific bug reports. You must
@@ -52,16 +52,14 @@ particular:
   small test case is the best way to report a bug, as it gives us an easy
   way to confirm the bug quickly.
 
-* **Don't** post to `django-developers`_ just to announce that you have
+* **Don't** post to |django-developers| just to announce that you have
   filed a bug report. All the tickets are mailed to another list,
-  `django-updates`_, which is tracked by developers and interested
+  |django-updates|, which is tracked by developers and interested
   community members; we see them as they are filed.
 
 To understand the lifecycle of your ticket once you have created it, refer to
 :doc:`triaging-tickets`.
 
-.. _django-updates: http://groups.google.com/group/django-updates
-
 Reporting user interface bugs and features
 ------------------------------------------
 
@@ -101,7 +99,7 @@ part of that. Here are some tips on how to make a request most effectively:
   gathers sufficient community support, we may consider it for inclusion in
   Django.
 
-* First request the feature on the `django-developers`_ list, not in the
+* First request the feature on the |django-developers| list, not in the
   ticket tracker. It'll get read more closely if it's on the mailing list.
   This is even more important for large-scale feature requests. We like to
   discuss any big changes to Django's core on the mailing list before
@@ -117,7 +115,7 @@ part of that. Here are some tips on how to make a request most effectively:
   useful.
 
 If core developers agree on the feature, then it's appropriate to create a
-ticket. Include a link the discussion on `django-developers`_ in the ticket
+ticket. Include a link the discussion on |django-developers| in the ticket
 description.
 
 As with most open-source projects, code talks. If you are willing to write the
@@ -133,7 +131,7 @@ How we make decisions
 ---------------------
 
 Whenever possible, we strive for a rough consensus. To that end, we'll often
-have informal votes on `django-developers`_ about a feature. In these votes we
+have informal votes on |django-developers| about a feature. In these votes we
 follow the voting style invented by Apache and used on Python itself, where
 votes are given as +1, +0, -0, or -1. Roughly translated, these votes mean:
 
@@ -146,7 +144,7 @@ votes are given as +1, +0, -0, or -1. Roughly translated, these votes mean:
 * -1: "I strongly disagree and would be very unhappy to see the idea turn
   into reality."
 
-Although these votes on `django-developers`_ are informal, they'll be taken very
+Although these votes on |django-developers| are informal, they'll be taken very
 seriously. After a suitable voting period, if an obvious consensus arises we'll
 follow the votes.
 
@@ -174,13 +172,11 @@ votes (or BDFL vetos) should be accompanied by an explanation that explains
 what it would take to convert that "-1" into at least a "+0".
 
 Whenever possible, these formal votes should be announced and held in
-public on the `django-developers`_ mailing list. However, overly sensitive
+public on the |django-developers| mailing list. However, overly sensitive
 or contentious issues -- including, most notably, votes on new core
 committers -- may be held in private.
 
 
 .. _searching: https://code.djangoproject.com/search
 .. _custom queries: https://code.djangoproject.com/query
-.. _django-developers: http://groups.google.com/group/django-developers
-.. _django-users: http://groups.google.com/group/django-users
 .. _#django: irc://irc.freenode.net/django

docs/internals/contributing/committing-code.txt

@@ -131,10 +131,10 @@ Django's Git repository:
   reasons for example) first discuss the situation with the core team.
 
 * For any medium-to-big changes, where "medium-to-big" is according to
-  your judgment, please bring things up on the `django-developers`_
+  your judgment, please bring things up on the |django-developers|
   mailing list before making the change.
 
-  If you bring something up on `django-developers`_ and nobody responds,
+  If you bring something up on |django-developers| and nobody responds,
   please don't take that to mean your idea is great and should be
   implemented immediately because nobody contested it. Django's lead
   developers don't have a lot of time to read mailing-list discussions
@@ -239,13 +239,13 @@ When a mistaken commit is discovered, please follow these guidelines:
 * If the original author can't be reached (within a reasonable amount
   of time -- a day or so) and the problem is severe -- crashing bug,
   major test failures, etc -- then ask for objections on the
-  `django-developers`_ mailing list then revert if there are none.
+  |django-developers| mailing list then revert if there are none.
 
 * If the problem is small (a feature commit after feature freeze,
   say), wait it out.
 
 * If there's a disagreement between the committer and the
-  reverter-to-be then try to work it out on the `django-developers`_
+  reverter-to-be then try to work it out on the |django-developers|
   mailing list. If an agreement can't be reached then it should
   be put to a vote.
 
@@ -260,5 +260,4 @@ When a mistaken commit is discovered, please follow these guidelines:
   For instance, if you did: ``git push upstream feature_antigravity``,
   just do a reverse push: ``git push upstream :feature_antigravity``.
 
-.. _django-developers: http://groups.google.com/group/django-developers
 .. _ticket tracker: https://code.djangoproject.com/newticket

docs/internals/contributing/index.txt

@@ -6,7 +6,7 @@ Django is a community that lives on its volunteers. As it keeps growing, we
 always need more people to help others. As soon as you learn Django, you can
 contribute in many ways:
 
-* Join the `django-users`_ mailing list and answer questions. This
+* Join the |django-users| mailing list and answer questions. This
   mailing list has a huge audience, and we really want to maintain a
   friendly and helpful atmosphere. If you're new to the Django community,
   you should read the `posting guidelines`_.
@@ -31,7 +31,7 @@ development:
 
 * :doc:`Report bugs <bugs-and-features>` in our `ticket tracker`_.
 
-* Join the `django-developers`_ mailing list and share your ideas for how
+* Join the |django-developers| mailing list and share your ideas for how
   to improve Django. We're always open to suggestions.
 
 * :doc:`Submit patches <writing-code/submitting-patches>` for new and/or
@@ -59,11 +59,9 @@ Browse the following sections to find out how:
    localizing
    committing-code
 
-.. _django-users: http://groups.google.com/group/django-users
 .. _posting guidelines: https://code.djangoproject.com/wiki/UsingTheMailingList
 .. _#django IRC channel: irc://irc.freenode.net/django
 .. _community page: https://www.djangoproject.com/community/
 .. _register it here: https://www.djangoproject.com/community/add/blogs/
-.. _django-developers: http://groups.google.com/group/django-developers
 .. _ticket tracker: https://code.djangoproject.com/newticket
 .. _easy pickings: https://code.djangoproject.com/query?status=!closed&easy=1

docs/internals/contributing/new-contributors.txt

@@ -139,7 +139,7 @@ FAQ
 
    First off, it's not personal. Django is entirely developed by volunteers
    (even the core developers), and sometimes folks just don't have time. The
-   best thing to do is to send a gentle reminder to the django-developers
+   best thing to do is to send a gentle reminder to the |django-developers|
    mailing list asking for review on the ticket, or to bring it up in the
    #django-dev IRC channel.
 

docs/internals/contributing/triaging-tickets.txt

@@ -311,9 +311,9 @@ A ticket can be resolved in a number of ways:
 * wontfix
       Used when a core developer decides that this request is not
       appropriate for consideration in Django. This is usually chosen after
-      discussion in the `django-developers`_ mailing list. Feel free to
+      discussion in the |django-developers| mailing list. Feel free to
       start or join in discussions of "wontfix" tickets on the
-      django-developers_ mailing list, but please do not reopen tickets
+      |django-developers| mailing list, but please do not reopen tickets
       closed as "wontfix" by a :doc:`core developer</internals/committers>`.
 
 * duplicate
@@ -334,7 +334,7 @@ If you believe that the ticket was closed in error -- because you're
 still having the issue, or it's popped up somewhere else, or the triagers have
 made a mistake -- please reopen the ticket and provide further information.
 Again, please do not reopen tickets that have been marked as "wontfix" by core
-developers and bring the issue to django-developers_ instead.
+developers and bring the issue to |django-developers| instead.
 
 .. _how-can-i-help-with-triaging:
 
@@ -358,7 +358,7 @@ Then, you can help out by:
 
 * Closing "Unreviewed" tickets as "needsinfo" when the description is too
   sparse to be actionnable, or when they're feature requests requiring a
-  discussion on `django-developers`_.
+  discussion on |django-developers|.
 
 * Correcting the "Needs tests", "Needs documentation", or "Has patch"
   flags for tickets where they are incorrectly set.
@@ -376,7 +376,7 @@ Then, you can help out by:
   reports about a particular part of Django, it may indicate we should
   consider refactoring that part of the code. If a trend is emerging,
   you should raise it for discussion (referencing the relevant tickets)
-  on `django-developers`_.
+  on |django-developers|.
 
 * Verify if patches submitted by other users are correct. If they do and
   also contain appropriate documentation and tests then move them to the
@@ -408,15 +408,14 @@ the ticket database:
 
 * Please **don't** reverse a decision that has been made by a :doc:`core
   developer</internals/committers>`. If you disagree with a decision that
-  has been made, please post a message to `django-developers`_.
+  has been made, please post a message to |django-developers|.
 
 * If you're unsure if you should be making a change, don't make the
   change but instead leave a comment with your concerns on the ticket,
-  or post a message to `django-developers`_. It's okay to be unsure,
+  or post a message to |django-developers|. It's okay to be unsure,
   but your input is still valuable.
 
 .. _Trac: https://code.djangoproject.com/
-.. _django-developers: http://groups.google.com/group/django-developers
 .. _i18n branch: https://code.djangoproject.com/browser/django/branches/i18n
 .. _`tags/releases`: https://code.djangoproject.com/browser/django/tags/releases
 .. _`easy pickings`: https://code.djangoproject.com/query?status=!closed&easy=1

docs/internals/contributing/writing-code/submitting-patches.txt

@@ -153,7 +153,7 @@ A "non-trivial" patch is one that is more than a simple bug fix. It's a patch
 that introduces Django functionality and makes some sort of design decision.
 
 If you provide a non-trivial patch, include evidence that alternatives have
-been discussed on `django-developers`_.
+been discussed on |django-developers|.
 
 If you're not sure whether your patch should be considered non-trivial, just
 ask.
@@ -262,6 +262,5 @@ Please don't forget to run ``compress.py`` and include the ``diff`` of the
 minified scripts when submitting patches for Django's javascript.
 
 .. _Closure Compiler: https://developers.google.com/closure/compiler/
-.. _django-developers: http://groups.google.com/group/django-developers
 .. _list of tickets with patches: https://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority
 .. _ticket tracker: https://code.djangoproject.com/newticket

docs/internals/howto-release-django.txt

@@ -311,8 +311,8 @@ Now you're ready to actually put the release out there. To do this:
    database (this will automatically flip it to ``False`` for all
    others); you can do this using the site's admin.
 
-#. Post the release announcement to the django-announce,
+#. Post the release announcement to the |django-announce|,
-   django-developers and django-users mailing lists. This should
+   |django-developers| and |django-users| mailing lists. This should
    include links to the announcement blog post and the release notes.
 
 Post-release

docs/internals/index.txt

@@ -17,6 +17,7 @@ the hood".
    :maxdepth: 2
 
    contributing/index
+   mailing-lists
    committers
    security
    release-process

docs/internals/mailing-lists.txt

@@ -0,0 +1,104 @@
+=============
+Mailing lists
+=============
+
+.. Important::
+
+    Please report security issues **only** to
+    security@djangoproject.com.  This is a private list only open to
+    long-time, highly trusted Django developers, and its archives are
+    not public. For further details, please see :doc:`our security
+    policies </internals/security>`.
+
+Django has several official mailing lists on Google Groups that are open to
+anyone.
+
+.. _django-users-mailing-list:
+
+``django-users``
+----------------
+
+This is the right place if you are looking to ask any question regarding the
+installation, usage, or debugging of Django.
+
+.. note::
+    If it's the first time you send an email to this list, your email must be
+    accepted first so don't worry if :ref:`your message does not appear
+    <message-does-not-appear-on-django-users>` instantly.
+
+* `django-users mailing archive`_
+* `django-users subscription email address`_
+* `django-users posting email`_
+
+.. _django-users mailing archive: http://groups.google.com/group/django-users/
+.. _django-users subscription email address: mailto:django-users+subscribe@googlegroups.com
+.. _django-users posting email: mailto:django-users@googlegroups.com
+
+.. _django-core-mentorship-mailing-list:
+
+``django-core-mentorship``
+--------------------------
+
+The Django Core Development Mentorship list is intended to provide a welcoming
+introductory environment for developers interested in contributing to core
+Django development.
+
+* `django-core-mentorship mailing archive`_
+* `django-core-mentorship subscription email address`_
+* `django-core-mentorship posting email`_
+
+.. _django-core-mentorship mailing archive: http://groups.google.com/group/django-core-mentorship/
+.. _django-core-mentorship subscription email address: mailto:django-core-mentorship+subscribe@googlegroups.com
+.. _django-core-mentorship posting email: mailto:django-core-mentorship@googlegroups.com
+
+.. _django-developers-mailing-list:
+
+``django-developers``
+---------------------
+
+The discussion about the development of Django itself takes place here.
+
+.. note::
+    Please make use of
+    :ref:`django-users mailing list <django-users-mailing-list>` if you want
+    to ask for tech support, doing so in this list is inappropriate.
+
+* `django-developers mailing archive`_
+* `django-developers subscription email address`_
+* `django-developers posting email`_
+
+.. _django-developers mailing archive: http://groups.google.com/group/django-developers/
+.. _django-developers subscription email address: mailto:django-developers+subscribe@googlegroups.com
+.. _django-developers posting email: mailto:django-developers@googlegroups.com
+
+.. _django-announce-mailing-list:
+
+``django-announce``
+-------------------
+
+A (very) low-traffic list for announcing new releases of Django and important
+bugfixes.
+
+* `django-announce mailing archive`_
+* `django-announce subscription email address`_
+* `django-announce posting email`_
+
+.. _django-announce mailing archive: http://groups.google.com/group/django-announce/
+.. _django-announce subscription email address: mailto:django-announce+subscribe@googlegroups.com
+.. _django-announce posting email: mailto:django-announce@googlegroups.com
+
+.. _django-updates-mailing-list:
+
+``django-updates``
+------------------
+
+All the ticket updates are mailed automatically to this list, which is tracked
+by developers and interested community members.
+
+* `django-updates mailing archive`_
+* `django-updates subscription email address`_
+* `django-updates posting email`_
+
+.. _django-updates mailing archive: http://groups.google.com/group/django-updates/
+.. _django-updates subscription email address: mailto:django-updates+subscribe@googlegroups.com
+.. _django-updates posting email: mailto:django-updates@googlegroups.com

docs/internals/security.txt

@@ -110,12 +110,11 @@ On the day of disclosure, we will take the following steps:
    relevant patches and new releases, and crediting the reporter of
    the issue (if the reporter wishes to be publicly identified).
 
-4. Post a notice to the `django-announce`_ mailing list that links to the blog
+4. Post a notice to the |django-announce| mailing list that links to the blog
    post.
 
 .. _the Python Package Index: http://pypi.python.org/pypi
 .. _the official Django development blog: https://www.djangoproject.com/weblog/
-.. _django-announce: http://groups.google.com/group/django-announce
 
 If a reported issue is believed to be particularly time-sensitive --
 due to a known exploit in the wild, for example -- the time between

docs/intro/contributing.txt

@@ -34,12 +34,11 @@ so that it can be of use to the widest audience.
 .. admonition:: Where to get help:
 
     If you're having trouble going through this tutorial, please post a message
-    to `django-developers`__ or drop by `#django-dev on irc.freenode.net`__ to
+    to |django-developers| or drop by `#django-dev on irc.freenode.net`__ to
     chat with other Django users who might be able to help.
 
 __ http://diveintopython.net/toc/index.html
 __ http://diveintopython3.net/
-__ http://groups.google.com/group/django-developers
 __ irc://irc.freenode.net/django-dev
 
 What does this tutorial cover?

docs/intro/tutorial01.txt

@@ -36,10 +36,9 @@ older versions of Django and install a newer one.
 .. admonition:: Where to get help:
 
     If you're having trouble going through this tutorial, please post a message
-    to `django-users`__ or drop by `#django on irc.freenode.net`__ to chat
+    to |django-users| or drop by `#django on irc.freenode.net`__ to chat
     with other Django users who might be able to help.
 
-__ http://groups.google.com/group/django-users
 __ irc://irc.freenode.net/django
 
 Creating a project

docs/intro/whatsnext.txt

@@ -125,11 +125,10 @@ ticket system and use your feedback to improve the documentation for everybody.
 
 Note, however, that tickets should explicitly relate to the documentation,
 rather than asking broad tech-support questions. If you need help with your
-particular Django setup, try the `django-users mailing list`_ or the `#django
+particular Django setup, try the |django-users| mailing list or the `#django
 IRC channel`_ instead.
 
 .. _ticket system: https://code.djangoproject.com/newticket?component=Documentation
-.. _django-users mailing list: http://groups.google.com/group/django-users
 .. _#django IRC channel: irc://irc.freenode.net/django
 
 In plain text

docs/misc/distributions.txt

@@ -26,11 +26,8 @@ For distributors
 ================
 
 If you'd like to package Django for distribution, we'd be happy to help out!
-Please join the `django-developers mailing list`_ and introduce yourself.
+Please join the |django-developers| mailing list and introduce yourself.
 
-We also encourage all distributors to subscribe to the `django-announce mailing
+We also encourage all distributors to subscribe to the |django-announce| mailing
-list`_, which is a (very) low-traffic list for announcing new releases of Django
+list, which is a (very) low-traffic list for announcing new releases of Django
 and important bugfixes.
-
-.. _django-developers mailing list: http://groups.google.com/group/django-developers/
-.. _django-announce mailing list: http://groups.google.com/group/django-announce/

docs/ref/contrib/index.txt

@@ -177,6 +177,4 @@ Other add-ons
 =============
 
 If you have an idea for functionality to include in ``contrib``, let us know!
-Code it up, and post it to the `django-users mailing list`_.
+Code it up, and post it to the |django-users| mailing list.
-
-.. _django-users mailing list: http://groups.google.com/group/django-users