[1.6.x] 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.

Backport of 3895d8899d from master

10 files changed, 134 insertions, 39 deletions

diff --git a/docs/internals/contributing/bugs-and-features.txt b/docs/internals/contributing/bugs-and-features.txt
index 53b0e1007d..fe55b0897d 100644
--- a/docs/internals/contributing/bugs-and-features.txt
+++ b/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
diff --git a/docs/internals/contributing/committing-code.txt b/docs/internals/contributing/committing-code.txt
index b81bdd2e04..72d0187cea 100644
--- a/docs/internals/contributing/committing-code.txt
+++ b/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
diff --git a/docs/internals/contributing/index.txt b/docs/internals/contributing/index.txt
index 92289125f9..a53db0a588 100644
--- a/docs/internals/contributing/index.txt
+++ b/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
diff --git a/docs/internals/contributing/new-contributors.txt b/docs/internals/contributing/new-contributors.txt
index e3b02dd878..80a87f1e8f 100644
--- a/docs/internals/contributing/new-contributors.txt
+++ b/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.
 
diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt
index 006d5806b9..f0425b0b83 100644
--- a/docs/internals/contributing/triaging-tickets.txt
+++ b/docs/internals/contributing/triaging-tickets.txt
@@ -308,9 +308,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
@@ -331,7 +331,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:
 
@@ -355,7 +355,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.
@@ -373,7 +373,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 are correct
   and also contain appropriate documentation and tests then move them to the
@@ -405,15 +405,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
diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt
index 8f8ddddab4..ce77e4eee4 100644
--- a/docs/internals/contributing/writing-code/submitting-patches.txt
+++ b/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.
@@ -198,6 +198,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
diff --git a/docs/internals/howto-release-django.txt b/docs/internals/howto-release-django.txt
index 1bd357ee2d..515b5ce1d8 100644
--- a/docs/internals/howto-release-django.txt
+++ b/docs/internals/howto-release-django.txt
@@ -310,8 +310,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,
-   django-developers and django-users mailing lists. This should
+#. Post the release announcement to the |django-announce|,
+   |django-developers| and |django-users| mailing lists. This should
    include links to the announcement blog post and the release notes.
 
 Post-release
diff --git a/docs/internals/index.txt b/docs/internals/index.txt
index 9a80a90286..cd38c28723 100644
--- a/docs/internals/index.txt
+++ b/docs/internals/index.txt
@@ -17,6 +17,7 @@ the hood".
    :maxdepth: 2
 
    contributing/index
+   mailing-lists
    committers
    security
    release-process
diff --git a/docs/internals/mailing-lists.txt b/docs/internals/mailing-lists.txt
new file mode 100644
index 0000000000..467c9b6898
--- /dev/null
+++ b/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
diff --git a/docs/internals/security.txt b/docs/internals/security.txt
index 9bac9d5195..332bdd6bda 100644
--- a/docs/internals/security.txt
+++ b/docs/internals/security.txt
@@ -108,12 +108,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: https://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