Advice for new contributors

New contributor and not sure what to do? Want to help but just don’t know howto get started? This is the section for you.

Basic tools and workflow

If you are new to contributing to Django, the Writing your first patch for Djangotutorial will give you an introduction to the tools and the workflow.

First steps

Start with these steps to discover Django’s development process.

  • Sign the Contributor License Agreement

The code that you write belongs to you or your employer. If yourcontribution is more than one or two lines of code, you need to sign theCLA. See the Contributor License Agreement FAQ for a more thoroughexplanation.

  • Triage tickets

If an unreviewed ticket reports a bug, try and reproduce it. If youcan reproduce it and it seems valid, make a note that you confirmed the bugand accept the ticket. Make sure the ticket is filed under the correctcomponent area. Consider writing a patch that adds a test for the bug’sbehavior, even if you don’t fix the bug itself. See more atHow can I help with triaging?

  • Look for tickets that are accepted and review patches to build familiaritywith the codebase and the process

Mark the appropriate flags if a patch needs docs or tests. Look through thechanges a patch makes, and keep an eye out for syntax that is incompatiblewith older but still supported versions of Python. Run the tests and make sure they pass.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 thetime it gets reviewed. Make sure it still applies cleanly and functions asexpected. Updating a patch is both useful and important! See more onSubmitting patches.

  • Write some documentation

Django’s documentation is great but it can always be improved. Did you finda typo? Do you think that something should be clarified? Go ahead andsuggest a documentation patch! See also the guide onWriting documentation.

Note

The reports page contains links to many useful Trac queries, includingseveral that are useful for triaging tickets and reviewing patches assuggested above.

Guidelines

As a newcomer on a large project, it’s easy to experience frustration. Here’ssome advice to make your work on Django more useful and rewarding.

  • Pick a subject area that you care about, that you are familiar with, orthat you want to learn about

You don’t already have to be an expert on the area you want to work on; youbecome an expert through your ongoing contributions to the code.

  • Analyze tickets’ context and history

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 whenthey were said. Support for an idea two years ago doesn’t necessarily meanthat the idea will still have support. You also need to pay attention to whohasn’t spoken – for example, if an experienced contributor hasn’t beenrecently involved in a discussion, then a ticket may not have the supportrequired to get into Django.

  • Start small

It’s easier to get feedback on a little issue than on a big one. See theeasy pickings.

  • If you’re going to engage in a big task, make sure that your idea hassupport first

This means getting someone else to confirm that a bug is real before you fixthe issue, and ensuring that there’s consensus on a proposed feature beforeyou go implementing it.

  • Be bold! Leave feedback!

Sometimes it can be scary to put your opinion out to the world and say “thisticket is correct” or “this patch needs work”, but it’s the only way theproject moves forward. The contributions of the broad Django communityultimately have a much greater impact than that of any one person. We can’tdo 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 assuch. Leave a comment instead, letting others know your thoughts. If you’remostly certain, but not completely certain, you might also try asking on IRCto 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, andrepeat. The shotgun approach of taking on lots of tickets and letting somefall 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 patchdoesn’t have docs and tests, there had better be a good reason. Argumentslike “I couldn’t find any existing tests of this feature” don’t carry muchweight–while it may be true, that means you have the extra-important job ofwriting the very first tests for that feature, not that you get a pass fromwriting tests altogether.

FAQ

  • This ticket I care about has been ignored for days/weeks/months! What canI do to get it committed?

First off, it’s not personal. Django is entirely developed by volunteers(except the Django fellow), and sometimes folks just don’t have time. Thebest thing to do is to send a gentle reminder to the django-developersmailing 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 RFCmyself?

Short answer: No. It’s always better to get another set of eyes on aticket. If you’re having trouble getting that second set of eyes, seequestion 1, above.