mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-10-24 06:06:09 +00:00
Code Issues 32 Releases Wiki Activity

Fixed #14401 -- Added a contributing howto guide for new users. Thank you to everyone who added their advice, feedback, and wisdom to the wiki article while constructing this new guide.

Browse Source 
git-svn-id: http://code.djangoproject.com/svn/django/trunk@15645 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Gabriel Hurley
2011-02-25 02:45:48 +00:00
parent c2518f55c7
commit c250b8840b
3 changed files with 424 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

247
docs/internals/contributing.txt
View File

@@ -2,9 +2,10 @@
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 many ways you can help Django's development:
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 many ways you can help Django's
development:
* Blog about Django. We syndicate all the Django blogs we know about on
the `community page`_; contact jacob@jacobian.org if you've got a blog
@@ -32,17 +33,25 @@ community. The rest of this document describes the details of how our community
works and how it handles bugs, mailing lists, and all the other minutiae of
Django development.
.. seealso::
This document contains specific details for contributing to
Django. However, many new contributors find this guide confusing
or intimidating at first. For a simpler introduction
to becoming a contributor please see the :doc:`/howto/contribute` guide.
.. _reporting-bugs:
Reporting bugs
==============
Well-written bug reports are *incredibly* helpful. However, there's a certain
amount of overhead involved in working with any bug tracking system, so your
amount of overhead involved in working with any bug tracking system so your
help in keeping our ticket tracker as useful as possible is appreciated. In
particular:
* **Do** read the :doc:`FAQ </faq/index>` to see if your issue might be a well-known question.
* **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
be a well-known question.
* **Do** `search the tracker`_ to see if your issue has already been filed.
@@ -60,12 +69,13 @@ particular:
`django-users`_ list, or the `#django`_ IRC channel for that.
* **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.
We like to discuss any big changes to Django's core on the
`django-developers`_ list before actually working on them.
* **Don't** reopen issues that have been marked "wontfix". 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** reopen issues that have been marked "wontfix". 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
@@ -73,8 +83,8 @@ particular:
* **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 triagers, so we
see them as they are filed.
(`django-updates`_), which is tracked by developers and interested
community members; we see them as they are filed.
.. _django-updates: http://groups.google.com/group/django-updates
@@ -90,23 +100,23 @@ not publicly readable.
In the event of a confirmed vulnerability in Django itself, we will take the
following actions:
* Acknowledge to the reporter that we've received the report and that a fix
is forthcoming. We'll give a rough timeline and ask the reporter to keep
the issue confidential until we announce it.
* Acknowledge to the reporter that we've received the report and that a
fix is forthcoming. We'll give a rough timeline and ask the reporter
to keep the issue confidential until we announce it.
* Halt all other development as long as is needed to develop a fix, including
patches against the current and two previous releases.
* Halt all other development as long as is needed to develop a fix,
including patches against the current and two previous releases.
* Determine a go-public date for announcing the vulnerability and the fix.
To try to mitigate a possible "arms race" between those applying the patch
and those trying to exploit the hole, we will not announce security
problems immediately.
To try to mitigate a possible "arms race" between those applying the
patch and those trying to exploit the hole, we will not announce
security problems immediately.
* Pre-notify everyone we know to be running the affected version(s) of
Django. We will send these notifications through private e-mail which will
include documentation of the vulnerability, links to the relevant patch(es),
and a request to keep the vulnerability confidential until the official
go-public date.
Django. We will send these notifications through private e-mail
which will include documentation of the vulnerability, links to the
relevant patch(es), and a request to keep the vulnerability
confidential until the official go-public date.
* Publicly announce the vulnerability and the fix on the pre-determined
go-public date. This will probably mean a new release of Django, but
@@ -115,8 +125,9 @@ following actions:
Submitting patches
==================
We're always grateful for patches to Django's code. Indeed, bug reports with
associated patches will get fixed *far* more quickly than those without patches.
We're always grateful for patches to Django's code. Indeed, bug reports
with associated patches will get fixed *far* more quickly than those
without patches.
"Claiming" tickets
------------------
@@ -132,16 +143,20 @@ fixing it (as measured by your coding ability, knowledge of Django internals
and time availability), claim it by following these steps:
* `Create an account`_ to use in our ticket system.
* If a ticket for this issue doesn't exist yet, create one in our
`ticket tracker`_.
* If a ticket for this issue already exists, make sure nobody else has
claimed it. To do this, look at the "Assigned to" section of the ticket.
If it's assigned to "nobody," then it's available to be claimed.
Otherwise, somebody else is working on this ticket, and you either find
another bug/feature to work on, or contact the developer working on the
ticket to offer your help.
* Log into your account, if you haven't already, by clicking "Login" in the
upper right of the ticket page.
* Claim the ticket by clicking the radio button next to "Accept ticket"
near the bottom of the page, then clicking "Submit changes."
@@ -158,11 +173,9 @@ Once you've claimed a ticket, you have a responsibility to work on that ticket
in a reasonably timely fashion. If you don't have time to work on it, either
unclaim it or don't claim it in the first place!
Ticket triagers go through the list of claimed tickets from time to
time, checking whether any progress has been made. If there's no sign of
progress on a particular claimed ticket for a week or two, a triager may ask
you to relinquish the ticket claim so that it's no longer monopolized and
somebody else can claim it.
If there's no sign of progress on a particular claimed ticket for a week or
two, another developer may ask you to relinquish the ticket claim so that it's
no longer monopolized and somebody else can claim it.
If you've claimed a ticket and it's taking a long time (days or weeks) to code,
keep everybody updated by posting comments on the ticket. If you don't provide
@@ -185,20 +198,21 @@ Patch style
* Make sure your code matches our `coding style`_.
* Submit patches in the format returned by the ``svn diff`` command.
An exception is for code changes that are described more clearly in plain
English than in code. Indentation is the most common example; it's hard to
read patches when the only difference in code is that it's indented.
An exception is for code changes that are described more clearly in
plain English than in code. Indentation is the most common example; it's
hard to read patches when the only difference in code is that it's
indented.
Patches in ``git diff`` format are also acceptable.
* When creating patches, always run ``svn diff`` from the top-level
``trunk`` directory -- i.e., the one that contains ``django``, ``docs``,
``tests``, ``AUTHORS``, etc. This makes it easy for other people to apply
your patches.
``tests``, ``AUTHORS``, etc. This makes it easy for other people to
apply your patches.
* Attach patches to a ticket in the `ticket tracker`_, using the "attach file"
button. Please *don't* put the patch in the ticket description or comment
unless it's a single line patch.
* Attach patches to a ticket in the `ticket tracker`_, using the "attach
file" button. Please *don't* put the patch in the ticket description
or comment unless it's a single line patch.
* Name the patch file with a ``.diff`` extension; this will let the ticket
tracker apply correct syntax highlighting, which is quite helpful.
@@ -209,11 +223,12 @@ Patch style
* The code required to fix a problem or add a feature is an essential part
of a patch, but it is not the only part. A good patch should also include
a regression test to validate the behavior that has been fixed (and prevent
the problem from arising again).
a regression test to validate the behavior that has been fixed
(and prevent the problem from arising again).
* If the code associated with a patch adds a new feature, or modifies behavior
of an existing feature, the patch should also contain documentation.
* If the code associated with a patch adds a new feature, or modifies
behavior of an existing feature, the patch should also contain
documentation.
Non-trivial patches
-------------------
@@ -233,8 +248,8 @@ the `required details`_. A number of tickets have patches, but those patches
don't meet all the requirements of a `good patch`_.
One way to help out is to *triage* bugs that have been reported by other
users. A couple of dedicated volunteers work on this regularly, but more help
is always appreciated.
users. The core team--as well as many community members--work on this
regularly, but more help is always appreciated.
Most of the workflow is based around the concept of a ticket's "triage stage".
This stage describes where in its lifetime a given ticket is at any time.
@@ -248,15 +263,18 @@ Since a picture is worth a thousand words, let's start there:
:width: 590
:alt: Django's ticket workflow
We've got two official roles here:
We've got two roles in this diagram:
* Core developers: people with commit access who make the big decisions
and write the bulk of the code.
* Core developers: people with commit access who are responsible for
making the big decisions, writing large portions of the code and
integrating the contributions of the community.
* Ticket triagers: trusted community members with a proven history of
working with the Django community. As a result of this history, they
have been entrusted by the core developers to make some of the smaller
decisions about tickets.
* Ticket triagers: anyone in the Django community who chooses to
become involved in Django's development process. Our Trac installation
is :ref:`intentionally left open to the public
<the-spirit-of-contributing>`, and anyone can triage tickets.
Django is a community project, and we encourage `triage by the
community`_.
Second, note the five triage stages:
@@ -279,22 +297,22 @@ Second, note the five triage stages:
adding to the framework if an excellent patch is submitted. These
tickets are not a high priority.
5. If a ticket has an associated patch (see below), a triager will review
the patch. If the patch is complete, it'll be marked as "ready for
checkin" so that a core developer knows to review and check in the
patches.
5. If a ticket has an associated patch (see below), it will be reviewed
by the community. If the patch is complete, it'll be marked as "ready
for checkin" so that a core developer knows to review and commit the
patch.
The second part of this workflow involves a set of flags the describe what the
ticket has or needs in order to be "ready for checkin":
"Has patch"
This means the ticket has an associated patch_. These will be
reviewed by the triage team to see if the patch is "good".
reviewed to see if the patch is "good".
"Needs documentation"
This flag is used for tickets with patches that need associated
documentation. Complete documentation of features is a prerequisite
before we can check a fix into the codebase.
before we can check them into the codebase.
"Needs tests"
This flags the patch as needing associated unit tests. Again, this is a
@@ -303,12 +321,13 @@ ticket has or needs in order to be "ready for checkin":
"Patch needs improvement"
This flag means that although the ticket *has* a patch, it's not quite
ready for checkin. This could mean the patch no longer applies
cleanly, or that the code doesn't live up to our standards.
cleanly, there is a flaw in the implementation, or that the code
doesn't meet our standards.
A ticket can be resolved in a number of ways:
"fixed"
Used by one of the core developers once a patch has been rolled into
Used by the core developers once a patch has been rolled into
Django and the issue is fixed.
"invalid"
@@ -321,8 +340,10 @@ 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, and you should
feel free to join in when it's something you care about.
discussion in the ``django-developers`` mailing list. Feel free to
start or join in discussions of "wontfix" tickets on the mailing list,
but please do not reopen tickets closed as "wontfix" by core
developers.
"duplicate"
Used when another ticket covers the same issue. By closing duplicate
@@ -334,27 +355,29 @@ A ticket can be resolved in a number of ways:
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 tell us why. Please do not
reopen tickets that have been marked as "wontfix" by core developers.
made a mistake -- please reopen the ticket and provide further information.
Please do not reopen tickets that have been marked as "wontfix" by core
developers.
.. _required details: `Reporting bugs`_
.. _good patch: `Patch style`_
.. _triage by the community: `Triage by the general community`_
.. _patch: `Submitting patches`_
Triage by the general community
-------------------------------
Although the core developers and ticket triagers make the big decisions in
the ticket triage process, there's also a lot that general community
members can do to help the triage process. In particular, you can help out by:
Although the core developers make the big decisions in the ticket triage
process, there's a lot that general community members can do to help the
triage process. In particular, you can help out by:
* Closing "Unreviewed" tickets as "invalid", "worksforme" or "duplicate."
* Promoting "Unreviewed" tickets to "Design decision needed" if a design
decision needs to be made, or "Accepted" in case of obvious bugs.
* Correcting the "Needs tests", "Needs documentation", or "Has patch" flags
for tickets where they are incorrectly set.
* Correcting the "Needs tests", "Needs documentation", or "Has patch"
flags for tickets where they are incorrectly set.
* Adding the `easy-pickings`_ keyword to tickets that are small and
relatively straightforward.
@@ -363,15 +386,15 @@ members can do to help the triage process. In particular, you can help out by:
any activity in a long time, it's possible that the problem has been
fixed but the ticket hasn't yet been closed.
* Contacting the owners of tickets that have been claimed but have not seen
any recent activity. If the owner doesn't respond after a week or so,
remove the owner's claim on the ticket.
* Contacting the owners of tickets that have been claimed but have not
seen any recent activity. If the owner doesn't respond after a week
or so, remove the owner's claim on the ticket.
* Identifying trends and themes in the tickets. If there a lot of bug 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`_.
* Identifying trends and themes in the tickets. If there a lot of bug
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`_.
However, we do ask the following of all general community members working in
the ticket database:
@@ -380,17 +403,19 @@ the ticket database:
make the final determination of the fate of a ticket, usually after
consultation with the community.
* Please **don't** promote tickets to "Ready for checkin" unless they are
*trivial* changes -- for example, spelling mistakes or broken links in
documentation.
* Please **don't** promote your own tickets to "Ready for checkin". You
may mark other people's tickets which you've reviewed as "Ready for
checkin", but you should get at minimum one other community member to
review a patch that you submit.
* Please **don't** reverse a decision that has been made by a core
developer. If you disagree with a discussion that has been made,
developer. If you disagree with a decision that has been made,
please post a message to `django-developers`_.
* Please be conservative in your actions. If you're unsure if you should
be making a change, don't make the change -- leave a comment with your
concerns on the ticket, or 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, but
your input is still valuable.
.. _contributing-translations:
@@ -429,7 +454,7 @@ to do:
* Once you are a member of a team choose the translation resource you
want update on the team page. For example the "core" resource refers
to the translation catalogue that contains all non-app translations.
Each of the contrib apps also have a resource -- prefixed with "contrib-".
Each of the contrib apps also have a resource (prefixed with "contrib-").
.. note::
For more information about how to use Transifex, see the
@@ -500,9 +525,9 @@ Various Django-specific code issues are detailed in this section.
Use of ``django.conf.settings``
-------------------------------
Modules should not in general use settings stored in ``django.conf.settings`` at
the top level (i.e. evaluated when the module is imported). The explanation for
this is as follows:
Modules should not in general use settings stored in ``django.conf.settings``
at the top level (i.e. evaluated when the module is imported). The explanation
for this is as follows:
Manual configuration of settings (i.e. not relying on the
``DJANGO_SETTINGS_MODULE`` environment variable) is allowed and possible as
@@ -512,10 +537,10 @@ follows::
settings.configure({}, SOME_SETTING='foo')
However, if any setting is accessed before the ``settings.configure`` line, this
will not work. (Internally, ``settings`` is a ``LazyObject`` which configures
itself automatically when the settings are accessed if it has not already been
configured).
However, if any setting is accessed before the ``settings.configure`` line,
this will not work. (Internally, ``settings`` is a ``LazyObject`` which
configures itself automatically when the settings are accessed if it has not
already been configured).
So, if there is a module containing some code as follows::
@@ -529,9 +554,9 @@ That means that the ability for third parties to import the module at the top
level is incompatible with the ability to configure the settings object
manually, or makes it very difficult in some circumstances.
Instead of the above code, a level of laziness or indirection must be used, such
as :class:`django.utils.functional.LazyObject`, :func:`django.utils.functional.lazy` or
``lambda``.
Instead of the above code, a level of laziness or indirection must be used,
such as `django.utils.functional.LazyObject``, ``django.utils.functional.lazy``
or ``lambda``.
Coding style
============
@@ -1085,14 +1110,15 @@ for feature branches:
trunk you'll need to find a core developer familiar with your DVCS of
choice who'll actually perform the merge.
If you do decided to start a distributed branch of Django and choose to make it
public, please add the branch to the `Django branches`_ wiki page.
If you do decided to start a distributed branch of Django and choose to
make it public, please add the branch to the `Django branches`_ wiki
page.
2. Feature branches using SVN have a higher bar. If you want a branch in SVN
itself, you'll need a "mentor" among the :doc:`core committers
</internals/committers>`. This person is responsible for actually creating
the branch, monitoring your process (see below), and ultimately merging
the branch into trunk.
2. Feature branches using SVN have a higher bar. If you want a branch
in SVN itself, you'll need a "mentor" among the :doc:`core committers
</internals/committers>`. This person is responsible for actually
creating the branch, monitoring your process (see below), and
ultimately merging the branch into trunk.
If you want a feature branch in SVN, you'll need to ask in
`django-developers`_ for a mentor.
@@ -1110,8 +1136,8 @@ successful Django branch.
DVCS branches are obviously not under central control, so we have no way of
enforcing these rules. However, if you're using a DVCS, following these rules
will give you the best chance of having a successful branch (read: merged back to
trunk).
will give you the best chance of having a successful branch (read: merged back
to trunk).
Developers with branches in SVN, however, **must** follow these rules. The
branch mentor will keep on eye on the branch and **will delete it** if these
@@ -1140,8 +1166,8 @@ Once the branch is stable and ready to be merged into the trunk, alert
After a branch has been merged, it should be considered "dead"; write access to
it will be disabled, and old branches will be periodically "trimmed." To keep
our SVN wrangling to a minimum, we won't be merging from a given branch into the
trunk more than once.
our SVN wrangling to a minimum, we won't be merging from a given branch into
the trunk more than once.
Using branches
--------------
@@ -1259,8 +1285,8 @@ if the discussion towards a consensus fizzles out without a concrete decision,
we use a more formal process.
Any core committer (see below) may call for a formal vote using the same
voting mechanism above. A proposition will be considered carried by the core team
if:
voting mechanism above. A proposition will be considered carried by the core
team if:
* There are three "+1" votes from members of the core team.
@@ -1307,8 +1333,9 @@ Partial committers
Decisions on new committers will follow the process explained above in `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.
To request commit access, please contact an existing committer privately.
Public requests for commit access are potential flame-war starters, and
will be ignored.
.. _community page: http://www.djangoproject.com/community/
.. _ticket tracker: http://code.djangoproject.com/newticket