Permalink
Browse files

Fixed #16469 -- Improved documentation of Django internals, including…

… the new backport policy. Many thanks to Aymeric Augustin.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16548 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 8f7b502 commit 127b7fdce8e89e5a8e349a7de817050ac5a64719 @jezdez jezdez committed Jul 19, 2011
@@ -2,22 +2,22 @@
Reporting bugs and requesting features
======================================
-Before reporting a bug or requesting a new feature please consider these
+Before reporting a bug or requesting a new feature, please consider these
general points:
* Check that someone hasn't already filed the bug or feature request by
`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`_.
* Don't use the ticket tracker for lengthy discussions, because they're
- likely to get lost. If a particular ticket is controversial, please move
+ likely to get lost. If a particular ticket is controversial, please move the
discussion to `django-developers`_.
.. _reporting-bugs:
@@ -33,19 +33,19 @@ particular:
* **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
be a well-known question.
- * **Do** ask on `django-users`_ *first* if you're not sure if what you're
- seeing is a bug.
+ * **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. Include as
- much information as you possibly can, complete with code snippets, test
- cases, etc. This means including a clear, concise description of the
- problem, and a clear set of instructions for replicating the problem.
- A minimal example that illustrates the bug in a nice small test case
- is the best possible bug report.
+ * **Do** write complete, reproducible, specific bug reports. You must
+ include a clear, concise description of the problem, and a set of
+ instructions for replicating it. Add as much debug information as you can:
+ code snippets, test cases, exception backtraces, screenshots, etc. A nice
+ 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 filed
- a bug report. All the tickets are mailed to another list
- (`django-updates`_), which is tracked by developers and interested
+ * **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
community members; we see them as they are filed.
To understand the lifecycle of your ticket once you have created it, refer to
@@ -95,8 +95,18 @@ Requesting features
We're always trying to make Django better, and your feature requests are a key
part of that. Here are some tips on how to make a request most effectively:
- * First request the feature on `django-developers`_, not in the ticket
- tracker. It'll get read more closely if it's on the mailing list.
+ * Make sure the feature actually requires changes in Django's core. If your
+ idea can be developed as an independent application or module — for
+ instance, you want to support another database engine — we'll probably
+ suggest that you to develop it independently. Then, if your project
+ gathers sufficient community support, we may consider it for inclusion in
+ Django.
+
+ * 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
+ actually working on them.
* Describe clearly and concisely what the missing feature is and how you'd
like to see it implemented. Include example code (non-functional is OK)
@@ -107,19 +117,16 @@ part of that. Here are some tips on how to make a request most effectively:
you'll need to explain it, if it isn't obvious why the feature would be
useful.
- * Don't use the ticket system to make large-scale feature requests.
- We like to discuss any big changes to Django's core on the
- `django-developers`_ list before actually working on them.
+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
+description.
As with most open-source projects, code talks. If you are willing to write the
-code for the feature yourself or if (even better) you've already written it,
+code for the feature yourself or, even better, if you've already written it,
it's much more likely to be accepted. If it's a large feature that might need
multiple developers, we're always happy to give you an experimental branch in
our repository; see the :doc:`writing-code/branch-policy`.
-To understand the lifecycle of your ticket once you have created it, refer to
-:doc:`triaging-tickets`.
-
See also: :ref:`documenting-new-features`.
.. _how-we-make-decisions:
@@ -141,9 +148,9 @@ 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
-seriously. After a suitable voting period, if an obvious consensus arises
-we'll follow the votes.
+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.
However, consensus is not always possible. If consensus cannot be reached, or
if the discussion towards a consensus fizzles out without a concrete decision,
@@ -175,7 +182,7 @@ committers -- may be held in private.
.. _searching: http://code.djangoproject.com/search
-.. _`custom queries`: https://code.djangoproject.com/query
+.. _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
+.. _#django: irc://irc.freenode.net/django
@@ -28,11 +28,9 @@ Partial committers
in question is likely to be sufficient.
Decisions on new committers will follow the process explained in
-:ref:`how-we-make-decisions`.
-
-To request commit access, please contact an existing committer privately.
-Public requests for commit access are potential flame-war starters, and
-will be ignored.
+:ref:`how-we-make-decisions`. To request commit access, please contact an
+existing committer privately. Public requests for commit access are potential
+flame-war starters, and will be ignored.
Committing guidelines
---------------------
@@ -69,12 +67,12 @@ repository:
* Separate bug fixes from feature changes.
- Bug fixes need to be added to the current bugfix branch (e.g. the
- ``1.0.X`` branch) as well as the current trunk.
+ Bug fixes need to be added to the current bugfix branch as well as the
+ current trunk.
* If your commit closes a ticket in the Django `ticket tracker`_, begin
your commit message with the text "Fixed #abc", where "abc" is the
- number of the ticket your commit fixes. Example: "Fixed #123 -- Adde
+ number of the ticket your commit fixes. Example: "Fixed #123 -- Added
support for foo". We've rigged Subversion and Trac so that any commit
message in that format will automatically close the referenced ticket
and post a comment to it with the full commit message.
@@ -83,7 +81,7 @@ repository:
first, then the "Fixed #abc." For example:
"magic-removal: Fixed #123 -- Added whizbang feature."
- For the curious: We're using a `Trac post-commit hook`_ for this.
+ For the curious: we're using a `Trac post-commit hook`_ for this.
.. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook
@@ -111,8 +109,8 @@ 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 django-dev
- then revert if there are none.
+ major test failures, etc -- then ask for objections on the
+ `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.
@@ -2,33 +2,51 @@
Contributing to Django
======================
-If you think working *with* Django is fun, wait until you start working *on*
-it. We're passionate about helping Django users make the jump to contributing
-members of the community, so there are several ways you can help Django's
-development:
+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
+ 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`_.
+
+ * Join the `#django IRC channel`_ on Freenode and answer questions. By
+ explaining Django to other users, you're going to learn a lot about the
+ framework yourself.
* Blog about Django. We syndicate all the Django blogs we know about on
the `community page`_; if you'd like to see your blog on that page you
can `register it here`_.
- * :doc:`Report bugs and request features<bugs-and-features>` in our
- `ticket tracker`_.
+ * Contribute to open-source Django projects, write some documentation, or
+ release your own code as an open-source pluggable application. The
+ ecosystem of pluggable applications is a big strength of Django, help us
+ build it!
+
+If you think working *with* Django is fun, wait until you start working *on*
+it. We're passionate about helping Django users make the jump to contributing
+members of the community, so there are several ways you can help Django's
+development:
+
+ * :doc:`Report bugs <bugs-and-features>` in our `ticket tracker`_.
* 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
+ * :doc:`Submit patches <writing-code/submitting-patches>` for new and/or
fixed behavior. If you're looking for an easy way to start contributing
to Django have a look at the `easy pickings`_ tickets.
- * :doc:`Improve the documentation<writing-documentation>` or
- :doc:`write unit tests<writing-code/unit-tests>`.
+ * :doc:`Improve the documentation <writing-documentation>` or
+ :doc:`write unit tests <writing-code/unit-tests>`.
- * :doc:`Triage tickets<triaging-tickets>` that have been created by other
- users.
+ * :doc:`Triage tickets and review patches <triaging-tickets>` created by
+ other users.
-... and many more ways! Really, **ANYONE** can do something to help make
-Django better and greater. Browse the following sections to find out how:
+Really, **ANYONE** can do something to help make Django better and greater!
+
+Browse the following sections to find out how:
.. toctree::
:maxdepth: 2
@@ -41,8 +59,11 @@ Django better and greater. Browse the following sections to find out how:
translations
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: http://www.djangoproject.com/community/
+.. _register it here: http://www.djangoproject.com/community/add/blogs/
.. _django-developers: http://groups.google.com/group/django-developers
.. _ticket tracker: http://code.djangoproject.com/newticket
-.. _community page: http://www.djangoproject.com/community/
-.. _`easy pickings`: http://code.djangoproject.com/query?status=!closed&easy=1
-.. _`register it here`: http://www.djangoproject.com/community/add/blogs/
+.. _easy pickings: http://code.djangoproject.com/query?status=!closed&easy=1
@@ -5,15 +5,14 @@ Advice for new contributors
New contributor and not sure what to do? Want to help but just don't know how
to get started? This is the section for you.
-* **Pick a subject area that you care about, that you are familiar with, or
- that you want to learn about**
+First steps
+-----------
- You don't already have to be an expert on the area you want to work on; you
- become an expert through your ongoing contributions to the code.
+Start with these easy tasks to discover Django's development process.
* **Triage tickets**
- If a ticket is unreviewed and reports a bug, try and reproduce it. If you
+ If an `unreviewed ticket`_ reports a bug, try and reproduce it. If you
can reproduce it and it seems valid, make a note that you confirmed the bug
and accept the ticket. Make sure the ticket is filed under the correct
component area. Consider writing a patch that adds a test for the bug's
@@ -44,7 +43,30 @@ to get started? This is the section for you.
:doc:`writing-documentation`, in particular the tips for
:ref:`improving-the-documentation`.
-* **Analyze the ticket's context and history**
+ .. note::
+
+ The `reports page`_ contains links to many useful Trac queries, including
+ several that are useful for triaging tickets and reviewing patches as
+ suggested above.
+
+ .. _reports page: http://code.djangoproject.com/wiki/Reports
+
+.. _unreviewed ticket: http://code.djangoproject.com/query?status=!closed&stage=Unreviewed
+
+
+Guidelines
+----------
+
+As a newcomer on a large project, it's easy to experience frustration. Here's
+some advice to make your work on Django more useful and rewarding.
+
+* **Pick a subject area that you care about, that you are familiar with, or
+ that you want to learn about**
+
+ You don't already have to be an expert on the area you want to work on; you
+ become an expert through your ongoing contributions to the code.
+
+* **Analyze tickets' context and history**
Trac isn't an absolute; the context is just as important as the words.
When reading Trac, you need to take into account who says things, and when
@@ -96,13 +118,7 @@ to get started? This is the section for you.
writing the very first tests for that feature, not that you get a pass from
writing tests altogether.
-.. note::
-
- The `Reports page`_ contains links to many useful Trac queries, including
- several that are useful for triaging tickets and reviewing patches as
- suggested above.
-
- .. _Reports page: http://code.djangoproject.com/wiki/Reports
+.. _easy pickings: http://code.djangoproject.com/query?status=!closed&easy=1
.. _new-contributors-faq:
@@ -114,7 +130,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.
@@ -130,8 +146,6 @@ FAQ
Design Decision Needed requires consensus about the right solution. At the
very least it needs consensus among the core developers, and ideally it has
consensus from the community as well. The best way to accomplish this is to
- start a thread on the Django Developers mailing list, and for very complex
+ start a thread on the django-developers mailing list, and for very complex
issues to start a wiki page summarizing the problem and the possible
solutions.
-
-.. _`easy pickings`: http://code.djangoproject.com/query?status=!closed&easy=1
Oops, something went wrong. Retry.

0 comments on commit 127b7fd

Please sign in to comment.