Committing code

This section is addressed to the Django committers and to anyone interested in knowing how code gets committed into Django core.

Commit access

Django has two types of committers:

Core committers
These are people who have a long history of contributions to Django’s codebase, a solid track record of being polite and helpful on the mailing lists, and a proven desire to dedicate serious time to Django’s development. The bar is high for full commit access.
Partial committers

These are people who are “domain experts.” They have direct check-in access to the subsystems that fall under their jurisdiction, and they’re given a formal vote in questions that involve their subsystems. This type of access is likely to be given to someone who contributes a large subframework to Django and wants to continue to maintain it.

Partial commit access is granted by the same process as full committers. However, the bar is set lower; proven expertise in the area in question is likely to be sufficient.

Decisions on new committers will follow the process explained 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.

Committing guidelines

Please follow these guidelines when committing code to Django’s Subversion repository:

  • For any medium-to-big changes, where “medium-to-big” is according to your judgment, please bring things up on the django-developers mailing list before making the change.

    If you bring something up on django-developers and nobody responds, please don’t take that to mean your idea is great and should be implemented immediately because nobody contested it. Django’s lead developers don’t have a lot of time to read mailing-list discussions immediately, so you may have to wait a couple of days before getting a response.

  • Write detailed commit messages in the past tense, not present tense.

    • Good: “Fixed Unicode bug in RSS API.”
    • Bad: “Fixes Unicode bug in RSS API.”
    • Bad: “Fixing Unicode bug in RSS API.”

  • For commits to a branch, prefix the commit message with the branch name. For example: “magic-removal: Added support for mind reading.”

  • Limit commits to the most granular change that makes sense. This means, use frequent small commits rather than infrequent large commits. For example, if implementing feature X requires a small change to library Y, first commit the change to library Y, then commit feature X in a separate commit. This goes a long way in helping all core Django developers follow your changes.

  • Separate bug fixes from feature changes.

    Bug fixes need to be added to the current bugfix branch as well as the current trunk.

  • If your commit closes a ticket in the Django ticket tracker, begin your commit message with the text “Fixed #abc”, where “abc” is the number of the ticket your commit fixes. Example: “Fixed #123 – Added support for foo”. We’ve rigged Subversion and Trac so that any commit message in that format will automatically close the referenced ticket and post a comment to it with the full commit message.

    If your commit closes a ticket and is in a branch, use the branch name first, then the “Fixed #abc.” For example: “magic-removal: Fixed #123 – Added whizbang feature.”

    For the curious: we’re using a Trac post-commit hook for this.

  • If your commit references a ticket in the Django ticket tracker but does not close the ticket, include the phrase “Refs #abc”, where “abc” is the number of the ticket your commit references. We’ve rigged Subversion and Trac so that any commit message in that format will automatically post a comment to the appropriate ticket.

  • Write commit messages for backports using this pattern:

    [<Django version>] Fixed <ticket> -- <description>

Backport of <revision> from <branch>.

    For example:

    [1.3.X] Fixed #17028 - Changed diveintopython.org -> diveintopython.net.

Backport of r17115 from trunk.

Reverting commits

Nobody’s perfect; mistakes will be committed. When a mistaken commit is discovered, please follow these guidelines:

  • Try very hard to ensure that mistakes don’t happen. Just because we have a reversion policy doesn’t relax your responsibility to aim for the highest quality possible. Really: double-check your work before you commit it in the first place!
  • If possible, have the original author revert his/her own commit.
  • Don’t revert another author’s changes without permission from the original author.
  • If the original author can’t be reached (within a reasonable amount of time – a day or so) and the problem is severe – crashing bug, major test failures, etc – then ask for objections on the django-developers mailing list then revert if there are none.
  • If the problem is small (a feature commit after feature freeze, say), wait it out.
  • If there’s a disagreement between the committer and the reverter-to-be then try to work it out on the django-developers mailing list. If an agreement can’t be reached then it should be put to a vote.
  • If the commit introduced a confirmed, disclosed security vulnerability then the commit may be reverted immediately without permission from anyone.
  • The release branch maintainer may back out commits to the release branch without permission if the commit breaks the release branch.
« previous | up | next »