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
2011-02-25 02:45:48 +00:00 · 2011-02-25 02:45:48 +00:00 · c250b8840b
parent c2518f55c7
commit c250b8840b
3 changed files with 424 additions and 110 deletions
--- a/docs/howto/contribute.txt
+++ b/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.
--- a/docs/howto/index.txt
+++ b/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
--- a/docs/internals/contributing.txt
+++ b/docs/internals/contributing.txt
@ -2,9 +2,10 @@
 Contributing to Django
 ======================
-If you think working *with* Django is fun, wait until you start working *on* it.
+If you think working *with* Django is fun, wait until you start working *on*
-We're passionate about helping Django users make the jump to contributing members
+it. We're passionate about helping Django users make the jump to contributing
-of the community, so there are many ways you can help Django's development:
+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`_
+      We like to discuss any big changes to Django's core on the
-      list before actually working on them.
+      `django-developers`_ list before actually working on them.
-    * **Don't** reopen issues that have been marked "wontfix". This mark means
+    * **Don't** reopen issues that have been marked "wontfix". This mark
-      that the decision has been made that we can't or won't fix this particular
+      means that the decision has been made that we can't or won't fix
-      issue.  If you're not sure why, please ask on `django-developers`_.
+      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
+      (`django-updates`_), which is tracked by developers and interested
-      see them as they are filed.
+      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
+    * Acknowledge to the reporter that we've received the report and that a
-      is forthcoming. We'll give a rough timeline and ask the reporter to keep
+      fix is forthcoming. We'll give a rough timeline and ask the reporter
-      the issue confidential until we announce it.
+      to keep the issue confidential until we announce it.
-    * Halt all other development as long as is needed to develop a fix, including
+    * Halt all other development as long as is needed to develop a fix,
-      patches against the current and two previous releases.
+      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
+      To try to mitigate a possible "arms race" between those applying the
-      and those trying to exploit the hole, we will not announce security
+      patch and those trying to exploit the hole, we will not announce
-      problems immediately.
+      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
+      Django. We will send these notifications through private e-mail
-      include documentation of the vulnerability, links to the relevant patch(es),
+      which will include documentation of the vulnerability, links to the
-      and a request to keep the vulnerability confidential until the official
+      relevant patch(es), and a request to keep the vulnerability
-      go-public date.
+      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
+We're always grateful for patches to Django's code. Indeed, bug reports
-associated patches will get fixed *far* more quickly than those without patches.
+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
+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 +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
+      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 +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
+      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 +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
+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 +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
+    * 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 +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
+    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 +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
+        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 +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
+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 +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
+    * 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 +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
+    * 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:
@ -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
+Modules should not in general use settings stored in ``django.conf.settings``
-the top level (i.e. evaluated when the module is imported). The explanation for
+at the top level (i.e. evaluated when the module is imported). The explanation
-this is as follows:
+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
+However, if any setting is accessed before the ``settings.configure`` line,
-will not work. (Internally, ``settings`` is a ``LazyObject`` which configures
+this will not work. (Internally, ``settings`` is a ``LazyObject`` which
-itself automatically when the settings are accessed if it has not already been
+configures itself automatically when the settings are accessed if it has not
-configured).
+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
+Instead of the above code, a level of laziness or indirection must be used,
-as :class:`django.utils.functional.LazyObject`, :func:`django.utils.functional.lazy` or
+such as `django.utils.functional.LazyObject``, ``django.utils.functional.lazy``
-``lambda``.
+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
+       If you do decided to start a distributed branch of Django and choose to
-       public, please add the branch to the `Django branches`_ wiki page.
+       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
+    2. Feature branches using SVN have a higher bar. If you want a branch
-       itself, you'll need a "mentor" among the :doc:`core committers
+       in SVN itself, you'll need a "mentor" among the :doc:`core committers
-       </internals/committers>`. This person is responsible for actually creating
+       </internals/committers>`. This person is responsible for actually
-       the branch, monitoring your process (see below), and ultimately merging
+       creating the branch, monitoring your process (see below), and
-       the branch into trunk.
+       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
+will give you the best chance of having a successful branch (read: merged back
-trunk).
+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
+our SVN wrangling to a minimum, we won't be merging from a given branch into
-trunk more than once.
+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
+voting mechanism above. A proposition will be considered carried by the core
-if:
+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
+To request commit access, please contact an existing committer privately.
-requests for commit access are potential flame-war starters, and will be ignored.
+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