Browse files

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: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent c2518f5 commit c250b8840b19c78fe87b614fee34cd1a46245c21 Gabriel Hurley committed Feb 25, 2011
Showing with 424 additions and 110 deletions.
  1. +286 −0 docs/howto/contribute.txt
  2. +1 −0 docs/howto/index.txt
  3. +137 −110 docs/internals/contributing.txt
@@ -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
+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
+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:
+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"
+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.
+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?"
+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:
+**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.
+ contribute
Oops, something went wrong.

0 comments on commit c250b88

Please sign in to comment.