Commit 3895d889 authored by Unai Zalakain's avatar Unai Zalakain Committed by Tim Graham
Browse files

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.
parent 8b001486

docs/conf.py

+8 −0
Original line number Diff line number Diff line
@@ -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

+8 −11
Original line number Diff line number Diff line
@@ -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

+4 −3
Original line number Diff line number Diff line
@@ -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

+11 −15
Original line number Diff line number Diff line
@@ -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

+4 −5
Original line number Diff line number Diff line
@@ -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