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 help in keeping our ticket tracker as useful as possible is appreciated. In particular:

• Do read the FAQ to see if your issue might be a well-known question.
• Do search the tracker to see if your issue has already been filed.
• Do ask on django-users first if you’re not sure if what you’re seeing is a bug.
• Do write complete, reproducible, specific bug reports. Include as much information as you possibly can, complete with code snippets, test cases, etc. This means including a clear, concise description of the problem, and a clear set of instructions for replicating the problem. A minimal example that illustrates the bug in a nice small test case is the best possible bug report.
• Don’t use the ticket system to ask support questions. Use the 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.
• 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 discussion to django-developers.
• 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.

Reporting security issues¶

Report security issues to security@djangoproject.com. This is a private list only open to long-time, highly trusted Django developers, and its archives are 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.
• 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.
• 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.
• Publicly announce the vulnerability and the fix on the pre-determined go-public date. This will probably mean a new release of Django, but in some cases it may simply be patches against current releases.

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.

Ticket triage¶

Unfortunately, not all bug reports in the ticket tracker provide all 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.

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. Along with a handful of flags, this field easily tells us what and who each ticket is waiting on.

Since a picture is worth a thousand words, let’s start there:

We’ve got two official roles here:

• Core developers: people with commit access who make the big decisions and write the bulk of the code.
• 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.

Second, note the five triage stages:

1. A ticket starts as “Unreviewed”, meaning that nobody has examined the ticket.
2. “Design decision needed” means “this concept requires a design decision,” which should be discussed either in the ticket comments or on django-developers. The “Design decision needed” step will generally only be used for feature requests. It can also be used for issues that might be bugs, depending on opinion or interpretation. Obvious bugs (such as crashes, incorrect query results, or non-compliance with a standard) skip this step and move straight to “Accepted”.
3. Once a ticket is ruled to be approved for fixing, it’s moved into the “Accepted” stage. This stage is where all the real work gets done.
4. In some cases, a ticket might get moved to the “Someday/Maybe” state. This means the ticket is an enhancement request that we might consider 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.

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”.

“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.

“Needs tests”

This flags the patch as needing associated unit tests. Again, this is a required part of a valid patch.

“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.

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 Django and the issue is fixed.

“invalid”

Used if the ticket is found to be incorrect. This means that the issue in the ticket is actually the result of a user error, or describes a problem with something other than Django, or isn’t a bug report or feature request at all (for example, some new users submit support queries as tickets).

“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.

“duplicate”

Used when another ticket covers the same issue. By closing duplicate tickets, we keep all the discussion in one place, which helps everyone.

“worksforme”

Used when the ticket doesn’t contain enough detail to replicate the original bug.

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.

Submitting and maintaining translations¶

Various parts of Django, such as the admin site and validation error messages, are internationalized. This means they display different text depending on a user’s language setting. For this, Django uses the same internationalization infrastructure that is available to Django applications that is described in the i18n documentation.

These translations are contributed by Django users worldwide. If you find an incorrect translation, or if you’d like to add a language that isn’t yet translated, here’s what to do:

• Join the Django i18n mailing list and introduce yourself.

• Create translations using the methods described in the i18n documentation. For this you will use the django-admin.py makemessages tool. In this particular case it should be run from the top-level django directory of the Django source tree.

  The script runs over the entire Django source tree and pulls out all strings marked for translation. It creates (or updates) a message file in the directory conf/locale (for example for pt-BR, the file will be conf/locale/pt-br/LC_MESSAGES/django.po).

• Make sure that django-admin.py compilemessages -l <lang> runs without producing any warnings.

• Repeat the last two steps for the djangojs domain (by appending the -d djangojs command line option to the django-admin.py invocations).

• Create a diff of the .po file(s) against the current Subversion trunk.

• Open a ticket in Django’s ticket system, set its Component field to Translations, and attach the patch to it.

Coding style¶

Please follow these coding standards when writing code for inclusion in Django:

• Unless otherwise specified, follow PEP 8.

  You could use a tool like pep8.py to check for some problems in this area, but remember that PEP 8 is only a guide, so respect the style of the surrounding code as a primary goal.

• Use four spaces for indentation.

• Use underscores, not camelCase, for variable, function and method names (i.e. poll.get_unique_voters(), not poll.getUniqueVoters).

• Use InitialCaps for class names (or for factory functions that return classes).

• Mark all strings for internationalization; see the i18n documentation for details.

• In docstrings, use “action words” such as:

  def foo():
      """
      Calculates something and returns the result.
      """
      pass
  

  Here's an example of what not to do:

  def foo():
      """
      Calculate something and return the result.
      """
      pass
  

• Please don't put your name in the code you contribute. Our policy is to keep contributors' names in the AUTHORS file distributed with Django -- not scattered throughout the codebase itself. Feel free to include a change to the AUTHORS file in your patch if you make more than a single trivial change.

Documentation style¶

We place a high importance on consistency and readability of documentation. (After all, Django was created in a journalism environment!)

Committing code¶

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 (e.g. the 1.0.X 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.

Unit tests¶

Django comes with a test suite of its own, in the tests directory of the Django tarball. It's our policy to make sure all tests pass at all times.

The tests cover:

• Models and the database API (tests/modeltests/).
• Everything else in core Django code (tests/regressiontests)
• Contrib apps (django/contrib/<contribapp>/tests, see below)

We appreciate any and all contributions to the test suite!

The Django tests all use the testing infrastructure that ships with Django for testing applications. See Testing Django applications for an explanation of how to write new tests.

./runtests.py --settings=path.to.django.settings

PYTHONPATH=..
./runtests.py --settings=settings generic_relations i18n

./runtests.py --settings=settings markup

Requesting features¶

We're always trying to make Django better, and your feature requests are a key part of that. Here are some tips on how to most effectively make a request:

• Request the feature on django-developers, not in the ticket tracker; it'll get read more closely if it's on the mailing list.
• Describe clearly and concisely what the missing feature is and how you'd like to see it implemented. Include example code (non-functional is OK) if possible.
• Explain why you'd like the feature. In some cases this is obvious, but since Django is designed to help real developers get real work done, you'll need to explain it, if it isn't obvious why the feature would be useful.

As with most open-source projects, code talks. If you are willing to write the code for the feature yourself or if (even better) you've already written it, it's much more likely to be accepted. If it's a large feature that might need multiple developers we're always happy to give you an experimental branch in our repository; see below.

Branch policy¶

In general, the trunk must be kept stable. People should be able to run production sites against the trunk at any time. Additionally, commits to trunk ought to be as atomic as possible -- smaller changes are better. Thus, large feature changes -- that is, changes too large to be encapsulated in a single patch, or changes that need multiple eyes on them -- must happen on dedicated branches.

This means that if you want to work on a large feature -- anything that would take more than a single patch, or requires large-scale refactoring -- you need to do it on a feature branch. Our development process recognizes two options for feature branches:

1. Feature branches using a distributed revision control system like Git, Mercurial, Bazaar, etc.

   If you're familiar with one of these tools, this is probably your best option since it doesn't require any support or buy-in from the Django core developers.

   However, do keep in mind that Django will continue to use Subversion for the foreseeable future, and this will naturally limit the recognition of your branch. Further, if your branch becomes eligible for merging to 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.

2. Feature branches using SVN have a higher bar. If you want a branch in SVN itself, you'll need a "mentor" among the core 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.

svn co http://code.djangoproject.com/svn/django/branches/<branch>/

svn switch http://code.djangoproject.com/svn/django/branches/<branch>/

# Trunk is a svn checkout of:
#   http://code.djangoproject.com/svn/django/trunk/
#
/path/to/trunk

# <branch> is a svn checkout of:
#   http://code.djangoproject.com/svn/django/branches/<branch>/
#
#/path/to/<branch>

# On windows a path may look like this:
# C:/path/to/<branch>

Deciding on features¶

Once a feature's been requested and discussed, eventually we'll have a decision about whether to include the feature or drop it.

Whenever possible, we strive for a rough consensus. To that end, we'll often have informal votes on django-developers about a feature. In these votes we follow the voting style invented by Apache and used on Python itself, where votes are given as +1, +0, -0, or -1. Roughly translated, these votes mean:

• +1: "I love the idea and I'm strongly committed to it."
• +0: "Sounds OK to me."
• -0: "I'm not thrilled, but I won't stand in the way."
• -1: "I strongly disagree and would be very unhappy to see the idea turn into reality."

Although these votes on django-developers are informal, they'll be taken very seriously. After a suitable voting period, if an obvious consensus arises we'll follow the votes.

However, consensus is not always possible. Tough decisions will be discussed by all full committers and finally decided by the Benevolent Dictators for Life, Adrian and Jacob.

Commit access¶

Django has two types of committers:

Full 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 very high for full commit access. It will only be granted by unanimous approval of all existing full committers, and the decision will err on the side of rejection.

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.

Like full committers, partial commit access is by unanimous approval of all full committers (and any other partial committers in the same area). However, the bar is set lower; proven expertise in the area in question is likely to be sufficient.

To request commit access, please contact an existing committer privately. Public requests for commit access are potential flame-war starters, and will be ignored.