Skip to content

Commit

Permalink
Fixed #16469 -- Improved documentation of Django internals, including…
Browse files Browse the repository at this point in the history 
… 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
@jezdez
jezdez committed Jul 19, 2011
1 parent 8f7b502 commit 127b7fd
Show file tree
Hide file tree
Showing 13 changed files with 489 additions and 417 deletions.
63 changes: 35 additions & 28 deletions docs/internals/contributing/bugs-and-features.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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)
Expand All @@ -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:
Expand All @@ -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,
Expand Down Expand Up @@ -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
20 changes: 9 additions & 11 deletions docs/internals/contributing/committing-code.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
---------------------
Expand Down Expand Up @@ -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.
Expand All @@ -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

Expand Down Expand Up @@ -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.
Expand Down
53 changes: 37 additions & 16 deletions docs/internals/contributing/index.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
48 changes: 31 additions & 17 deletions docs/internals/contributing/new-contributors.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:

Expand All @@ -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.

Expand All @@ -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
Loading

0 comments on commit 127b7fd

Please sign in to comment.