[1.2.X] 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.

Backport of [15645] from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@15646 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/howto/contribute.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
+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.

docs/howto/index.txt

@@ -11,6 +11,7 @@ you quickly accomplish common tasks.
 
    apache-auth
    auth-remote-user
+   contribute
    custom-management-commands
    custom-model-fields
    custom-template-tags

docs/internals/contributing.txt

@@ -158,11 +158,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
+If there's no sign of progress on a particular claimed ticket for a week or
-time, checking whether any progress has been made. If there's no sign of
+two, another developer may ask you to relinquish the ticket claim so that it's
-progress on a particular claimed ticket for a week or two, a triager may ask
+no longer monopolized and somebody else can claim it.
-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 +183,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
+      An exception is for code changes that are described more clearly in
-      English than in code. Indentation is the most common example; it's hard to
+      plain English than in code. Indentation is the most common example; it's
-      read patches when the only difference in code is that it's indented.
+      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
+      ``tests``, ``AUTHORS``, etc. This makes it easy for other people to
-      your patches.
+      apply your patches.
 
-    * Attach patches to a ticket in the `ticket tracker`_, using the "attach file"
+    * Attach patches to a ticket in the `ticket tracker`_, using the "attach
-      button. Please *don't* put the patch in the ticket description or comment
+      file" button. Please *don't* put the patch in the ticket description
-      unless it's a single line patch.
+      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 +208,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
+      a regression test to validate the behavior that has been fixed
-      the problem from arising again).
+      (and prevent the problem from arising again).
 
-    * If the code associated with a patch adds a new feature, or modifies behavior
+    * If the code associated with a patch adds a new feature, or modifies
-      of an existing feature, the patch should also contain documentation.
+      behavior of an existing feature, the patch should also contain
+      documentation.
 
 Non-trivial patches
 -------------------
@@ -233,8 +233,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
+users. The core team--as well as many community members--work on this
-is always appreciated.
+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 +248,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
+    * Core developers: people with commit access who are responsible for
-      and write the bulk of the code.
+      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
+    * Ticket triagers: anyone in the Django community who chooses to
-      working with the Django community. As a result of this history, they
+      become involved in Django's development process. Our Trac installation
-      have been entrusted by the core developers to make some of the smaller
+      is :ref:`intentionally left open to the public
-      decisions about tickets.
+      <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 +282,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
+    5. If a ticket has an associated patch (see below), it will be reviewed
-       the patch. If the patch is complete, it'll be marked as "ready for
+       by the community. If the patch is complete, it'll be marked as "ready
-       checkin" so that a core developer knows to review and check in the
+       for checkin" so that a core developer knows to review and commit the
-       patches.
+       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 +306,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 +325,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
+        discussion in the ``django-developers`` mailing list. Feel free to
-        feel free to join in when it's something you care about.
+        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 +340,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
+made a mistake -- please reopen the ticket and provide further information.
-reopen tickets that have been marked as "wontfix" by core developers.
+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
+Although the core developers make the big decisions in the ticket triage
-the ticket triage process, there's also a lot that general community
+process, there's a lot that general community members can do to help the
-members can do to help the triage process. In particular, you can help out by:
+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
+    * Correcting the "Needs tests", "Needs documentation", or "Has patch"
-      for tickets where they are incorrectly set.
+      flags for tickets where they are incorrectly set.
 
     * Adding the `easy-pickings`_ keyword to tickets that are small and
       relatively straightforward.
@@ -363,15 +371,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
+    * Contacting the owners of tickets that have been claimed but have not
-      any recent activity. If the owner doesn't respond after a week or so,
+      seen any recent activity. If the owner doesn't respond after a week
-      remove the owner's claim on the ticket.
+      or so, remove the owner's claim on the ticket.
 
-    * Identifying trends and themes in the tickets. If there a lot of bug reports
+    * Identifying trends and themes in the tickets. If there a lot of bug
-      about a particular part of Django, it may indicate we should consider
+      reports about a particular part of Django, it may indicate we should
-      refactoring that part of the code. If a trend is emerging, you should
+      consider refactoring that part of the code. If a trend is emerging,
-      raise it for discussion (referencing the relevant tickets) on
+      you should raise it for discussion (referencing the relevant tickets)
-      `django-developers`_.
+      on `django-developers`_.
 
 However, we do ask the following of all general community members working in
 the ticket database:
@@ -380,17 +388,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
+    * Please **don't** promote your own tickets to "Ready for checkin". You
-      *trivial* changes -- for example, spelling mistakes or broken links in
+      may mark other people's tickets which you've reviewed as "Ready for
-      documentation.
+      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
+    * If you're unsure if you should be making a change, don't make the change
-      be making a change, don't make the change -- leave a comment with your
+      but instead leave a comment with your concerns on the ticket, or
-      concerns on the ticket, or post a message to `django-developers`_.
+      post a message to `django-developers`_. It's okay to be unsure, but
+      your input is still valuable.
 
 .. _contributing-translations: