Version 10 (modified by russellm, 6 years ago) (diff)

Added notes on "reading" trac, following a django-dev discussion

Contributing HowTo

This page is a place to gather information about "the spirit of contributing to Django", how to interpret the various (confusing) stages and flags in Trac, and friendly tips on how new contributors can get started. This information will eventually be compiled into a patch and merged into a permanent home in the Django Docs.

The topic comes up regularly on the Django Developers mailing list, and people have offered lots of good information in the past. Contributions and improvements are encouraged.

This is *not* a place for suggestions on how the current process could be improved, or ways that Trac could be better. Let's stick to what *is* for now... ;-)

A couple useful threads for mining on Django Developers:

And a couple items that were mentioned that would be nice:

  • Alex mentioned possibly doing a screencast on "how to contribute to Django"
  • There was a suggestion to have a "how to contribute" step-by-step tutorial with examples of both good and bad tickets.

Understanding Trac

What the various statuses "really" mean...

Django uses Trac as its 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 statuses isn't immediately obvious, and the statuses themselves have names that can be misinterpreted.

What Django's statuses "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 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 status 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.

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 you care about/are familiar with/want to learn about. (needs more text)
  • Triage Tickets. If a ticket is unaccepted and reports a bug, try and duplicate it. If you can 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 underlying issue.
  • 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.
  • Keep old patches up to date. Oftentimes the codebase will change between a patch being submitted and the time it gets reviewed. Making sure it still applies cleanly and functions as expected is both useful and important!
  • Trac isn't an absolute; the context is just as important as the literal message. When reading Trac, you need to take into account who says things, and when they were said. Support 2 years ago by a core team member 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.
  • If you're going to engage in a big task, you should make sure that your idea has support first. This means getting someone else to confirm that a bug is real before you spend a whole lot of time fixing the issue, and confirming that the core team supports a proposed feature before you spend a whole lot of time implementing it.
  • Be bold! Sometimes it can be scary to put your opinion out to the world and say "this ticket/patch is good or bad", 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!

"The Spirit of Contributing"

The collective knowledge of how things really get done that keeps the community functioning and happy.

Something about ponies... and probably some wise words from folks who have been around a while.


Questions that come up regularly, anything that's been overlooked, doesn't fit in its own section, etc....

  1. 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, 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.
  1. I'm sure my ticket is 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.
  1. 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.
  1. My ticket has been in RFC forever! What should I do?
    • The Ready For Checkin status is essentially a notice to core committers. They're humans with limited time and lots of demands on that time. They absolutely know to be looking for RFC tickets, and they all try to work through RFC tickets as a matter of priority. As with any other case of "my ticket is being ignored", gently raising awareness on Django Developers or the #django-dev IRC channel are the best ways to move things along. All tickets marked as RFC will be dealt with prior to a release.
Back to Top