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.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@15645 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Gabriel Hurley
parent
c2518f55c7
commit
c250b8840b
|
|
@ -0,0 +1,286 @@
|
|||
===========================
|
||||
How to contribute to Django
|
||||
===========================
|
||||
|
||||
Django is developed 100% by the community, and the more people that are actively
|
||||
involved in the code the better Django will be. We recognize that contributing
|
||||
to Django can be daunting at first and sometimes confusing even to
|
||||
veterans. While we have our official "Contributing to Django" documentation
|
||||
which spells out the technical details of triaging tickets and submitting
|
||||
patches, it leaves a lot of room for interpretation. This guide aims to offer
|
||||
more general advice on issues such as how to interpret the various stages and
|
||||
flags in Trac, and how new contributors can get started.
|
||||
|
||||
.. seealso::
|
||||
|
||||
This guide is meant to answer the most common questions about
|
||||
contributing to Django, however it is no substitute for the
|
||||
:doc:`/internals/contributing` reference. Please make sure to
|
||||
read that document to understand the specific details
|
||||
involved in reporting issues and submitting patches.
|
||||
|
||||
.. _the-spirit-of-contributing:
|
||||
|
||||
"The Spirit of Contributing"
|
||||
============================
|
||||
|
||||
Django uses Trac_ for managing our progress, and Trac is a community-tended
|
||||
garden of the bugs people have found and the features people would like to see
|
||||
added. As in any garden, sometimes there are weeds to be pulled and sometimes
|
||||
there are flowers and vegetables that need picking. We need your help to sort
|
||||
out one from the other, and in the end we all benefit together.
|
||||
|
||||
Like all gardens, we can aspire to perfection but in reality there's no such
|
||||
thing. Even in the most pristine garden there are still snails and insects. In a
|
||||
community garden there are also helpful people who--with the best of
|
||||
intentions--fertilize the weeds and poison the roses. It's the job of the
|
||||
community as a whole to self-manage, keep the problems to a minimum, and educate
|
||||
those coming into the community so that they can become valuable contributing
|
||||
members.
|
||||
|
||||
Similarly, while we aim for Trac to be a perfect representation of the state of
|
||||
Django's progress, we acknowledge that this simply will not happen. By
|
||||
distributing the load of Trac maintenance to the community, we accept that there
|
||||
will be mistakes. Trac is "mostly accurate", and we give allowances for the fact
|
||||
that sometimes it will be wrong. That's okay. We're perfectionists with
|
||||
deadlines.
|
||||
|
||||
We rely on the community to keep participating, keep tickets as accurate as
|
||||
possible, and raise issues for discussion on our mailing lists when there is
|
||||
confusion or disagreement.
|
||||
|
||||
Django is a community project, and every contribution helps. We can't do this
|
||||
without YOU!
|
||||
|
||||
.. _Trac: http://code.djangoproject.com/
|
||||
|
||||
Understanding Trac
|
||||
==================
|
||||
|
||||
Trac is Django's sole official issue tracker. All known bugs, desired features
|
||||
and ideas for changes are logged there.
|
||||
|
||||
However, Trac can be quite confusing even to veteran contributors. Having to
|
||||
look at both flags and triage stages isn't immediately obvious, and the stages
|
||||
themselves can be misinterpreted.
|
||||
|
||||
What Django's triage stages "really mean"
|
||||
-----------------------------------------
|
||||
|
||||
Unreviewed
|
||||
~~~~~~~~~~
|
||||
|
||||
The ticket has not been reviewed by anyone who felt qualified to make a judgment
|
||||
about whether the ticket contained a valid issue, a viable feature, or ought to
|
||||
be closed for any of the various reasons.
|
||||
|
||||
Accepted
|
||||
~~~~~~~~
|
||||
|
||||
The big grey area! The absolute meaning of "accepted" is that the issue
|
||||
described in the ticket is valid and is in some stage of being worked on. Beyond
|
||||
that there are several considerations
|
||||
|
||||
|
||||
* **Accepted + No Flags**
|
||||
|
||||
The ticket is valid, but no one has submitted a patch for it yet. Often this
|
||||
means you could safely start writing a patch for it.
|
||||
|
||||
* **Accepted + Has Patch**
|
||||
|
||||
The ticket is waiting for people to review the supplied patch. This means
|
||||
downloading the patch and trying it out, verifying that it contains tests and
|
||||
docs, running the test suite with the included patch, and leaving feedback on
|
||||
the ticket.
|
||||
|
||||
|
||||
* **Accepted + Has Patch + (any other flag)**
|
||||
|
||||
This means the ticket has been reviewed, and has been found to need further
|
||||
work. "Needs tests" and "Needs documentation" are self-explanatory. "Patch
|
||||
needs improvement" will generally be accompanied by a comment on the ticket
|
||||
explaining what is needed to improve the code.
|
||||
|
||||
Design Decision Needed
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This stage is for issues which may be contentious, may be backwards
|
||||
incompatible, or otherwise involve high-level design decisions. These decisions
|
||||
are generally made by the core committers, however that is not a
|
||||
requirement. See the FAQ below for "My ticket has been in DDN forever! What
|
||||
should I do?"
|
||||
|
||||
Ready For Checkin
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
The ticket was reviewed by any member of the community other than the person who
|
||||
supplied the patch and found to meet all the requirements for a commit-ready
|
||||
patch. A core committer now needs to give the patch a final review prior to
|
||||
being committed. See the FAQ below for "My ticket has been in RFC forever! What
|
||||
should I do?"
|
||||
|
||||
Someday/Maybe?
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Generally only used for vague/high-level features or design ideas. These tickets
|
||||
are uncommon and overall less useful since they don't describe concrete
|
||||
actionable issues.
|
||||
|
||||
Fixed on a branch
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Used to indicate that a ticket is resolved as part of a major body of work that
|
||||
will eventually be merged to trunk. Tickets in this stage generally don't need
|
||||
further work. This may happen in the case of major features/refactors in each
|
||||
release cycle, or as part of the annual Google Summer of Code efforts.
|
||||
|
||||
Example Trac workflow
|
||||
---------------------
|
||||
|
||||
Here we see the life-cycle of an average ticket:
|
||||
|
||||
* Alice creates a ticket, and uploads an incomplete patch (no tests, incorrect
|
||||
implementation).
|
||||
|
||||
* Bob reviews the patch, marks it "Accepted", "needs tests", and "patch needs
|
||||
improvement", and leaves a comment telling Alice how the patch could be
|
||||
improved.
|
||||
|
||||
* Alice updates the patch, adding tests (but not changing the
|
||||
implementation). She removes the two flags.
|
||||
|
||||
* Charlie reviews the patch and resets the "patch needs improvement" flag with
|
||||
another comment about improving the implementation.
|
||||
|
||||
* Alice updates the patch, fixing the implementation. She removes the "patch
|
||||
needs improvement" flag.
|
||||
|
||||
* Daisy reviews the patch, and marks it RFC.
|
||||
|
||||
* Jacob reviews the RFC patch, applies it to his checkout, and commits it.
|
||||
|
||||
Some tickets require much less feedback than this, but then again some tickets
|
||||
require much much more.
|
||||
|
||||
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.**
|
||||
|
||||
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.
|
||||
|
||||
* **Triage tickets.**
|
||||
|
||||
If a ticket is unreviewed and reports a bug, try and duplicate it. If you can
|
||||
duplicate 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 behavior, even
|
||||
if you don't fix the bug itself.
|
||||
|
||||
* **Look for tickets that are accepted and review patches to build familiarity
|
||||
with the codebase and the process.**
|
||||
|
||||
Mark the appropriate flags if a patch needs docs or tests. Look through the
|
||||
changes a patch makes, and keep an eye out for syntax that is incompatible
|
||||
with older but still supported versions of Python. Run the tests and make sure
|
||||
they pass on your system. Where possible and relevant, try them out on a
|
||||
database other than SQLite. Leave comments and feedback!
|
||||
|
||||
* **Keep old patches up to date.**
|
||||
|
||||
Oftentimes the codebase will change between a patch being submitted and the
|
||||
time it gets reviewed. Make sure it still applies cleanly and functions as
|
||||
expected. Simply updating a patch is both useful and important!
|
||||
|
||||
* **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
|
||||
they were said. Support for an idea two years ago doesn't necessarily mean
|
||||
that the idea will still have support. You also need to pay attention to who
|
||||
*hasn't* spoken -- for example, if a core team member hasn't been recently
|
||||
involved in a discussion, then a ticket may not have the support required to
|
||||
get into trunk.
|
||||
|
||||
* **Start small.**
|
||||
|
||||
It's easier to get feedback on a little issue than on a big one.
|
||||
|
||||
* **If you're going to engage in a big task, make sure that your idea has
|
||||
support first.**
|
||||
|
||||
This means getting someone else to confirm that a bug is real before you fix
|
||||
the issue, and ensuring that the core team supports a proposed feature before
|
||||
you go implementing it.
|
||||
|
||||
* **Be bold! Leave feedback!**
|
||||
|
||||
Sometimes it can be scary to put your opinion out to the world and say "this
|
||||
ticket is correct" or "this patch needs work", but it's the only way the
|
||||
project moves forward. The contributions of the broad Django community
|
||||
ultimately have a much greater impact than that of the core developers. We
|
||||
can't do it without YOU!
|
||||
|
||||
* **Err on the side of caution when marking things Ready For Check-in.**
|
||||
|
||||
If you're really not certain if a ticket is ready, don't mark it as
|
||||
such. Leave a comment instead, letting others know your thoughts. If you're
|
||||
mostly certain, but not completely certain, you might also try asking on IRC
|
||||
to see if someone else can confirm your suspicions.
|
||||
|
||||
* **Wait for feedback, and respond to feedback that you receive.**
|
||||
|
||||
Focus on one or two tickets, see them through from start to finish, and
|
||||
repeat. The shotgun approach of taking on lots of tickets and letting some
|
||||
fall by the wayside ends up doing more harm than good.
|
||||
|
||||
* **Be rigorous.**
|
||||
|
||||
When we say ":pep:`8`, and must have docs and tests", we mean it. If a patch
|
||||
doesn't have docs and tests, there had better be a good reason. Arguments like
|
||||
"I couldn't find any existing tests of this feature" don't carry much
|
||||
weight--while it may be true, that means you have the extra-important job of
|
||||
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
|
||||
|
||||
|
||||
FAQs
|
||||
====
|
||||
|
||||
**This ticket I care about has been ignored for days/weeks/months! What can I do
|
||||
to get it committed?**
|
||||
|
||||
* First off, it's not personal. Django is entirely developed by volunteers (even
|
||||
the core devs), and sometimes folks just don't have time. The 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.
|
||||
|
||||
|
||||
**I'm sure my ticket is absolutely 100% perfect, can I mark it as RFC myself?**
|
||||
|
||||
* Short answer: No. It's always better to get another set of eyes on a
|
||||
ticket. If you're having trouble getting that second set of eyes, see question
|
||||
1, above.
|
||||
|
||||
|
||||
**My ticket has been in DDN forever! What should I do?**
|
||||
|
||||
* 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
|
||||
issues to start a wiki page summarizing the problem and the possible
|
||||
solutions.
|
||||
|
|
@ -11,6 +11,7 @@ you quickly accomplish common tasks.
|
|||
|
||||
apache-auth
|
||||
auth-remote-user
|
||||
contribute
|
||||
custom-management-commands
|
||||
custom-model-fields
|
||||
custom-template-tags
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue