| 1 |
=========================== |
| 2 |
Advice for new contributors |
| 3 |
=========================== |
| 4 |
|
| 5 |
New contributor and not sure what to do? Want to help but just don't know how |
| 6 |
to get started? This is the section for you. |
| 7 |
|
| 8 |
.. admonition:: Get up and running! |
| 9 |
|
| 10 |
If you are new to contributing to Django, the :doc:`/intro/contributing` |
| 11 |
tutorial will give you an introduction to the tools and the workflow. |
| 12 |
|
| 13 |
This page contains more general advice on ways you can contribute to Django, |
| 14 |
and how to approach that. |
| 15 |
|
| 16 |
If you are looking for a reference on the details of making code contributions, |
| 17 |
see the :doc:`/internals/contributing/writing-code/index` documentation. |
| 18 |
|
| 19 |
First steps |
| 20 |
=========== |
| 21 |
|
| 22 |
Start with these steps to discover Django's development process. |
| 23 |
|
| 24 |
Triage tickets |
| 25 |
-------------- |
| 26 |
|
| 27 |
If an `unreviewed ticket`_ reports a bug, try and reproduce it. If you can |
| 28 |
reproduce it and it seems valid, make a note that you confirmed the bug and |
| 29 |
accept the ticket. Make sure the ticket is filed under the correct component |
| 30 |
area. Consider writing a patch that adds a test for the bug's behavior, even if |
| 31 |
you don't fix the bug itself. See more at :ref:`how-can-i-help-with-triaging` |
| 32 |
|
| 33 |
Review patches of accepted tickets |
| 34 |
---------------------------------- |
| 35 |
|
| 36 |
This will help you build familiarity with the codebase and processes. Mark the |
| 37 |
appropriate flags if a patch needs docs or tests. Look through the changes a |
| 38 |
patch makes, and keep an eye out for syntax that is incompatible with older but |
| 39 |
still supported versions of Python. :doc:`Run the tests |
| 40 |
</internals/contributing/writing-code/unit-tests>` and make sure they pass. |
| 41 |
Where possible and relevant, try them out on a database other than SQLite. |
| 42 |
Leave comments and feedback! |
| 43 |
|
| 44 |
Keep old patches up-to-date |
| 45 |
--------------------------- |
| 46 |
|
| 47 |
Oftentimes the codebase will change between a patch being submitted and the |
| 48 |
time it gets reviewed. Make sure it still applies cleanly and functions as |
| 49 |
expected. Updating a patch is both useful and important! See more on |
| 50 |
:doc:`writing-code/submitting-patches`. |
| 51 |
|
| 52 |
Write some documentation |
| 53 |
------------------------ |
| 54 |
|
| 55 |
Django's documentation is great but it can always be improved. Did you find a |
| 56 |
typo? Do you think that something should be clarified? Go ahead and suggest a |
| 57 |
documentation patch! See also the guide on :doc:`writing-documentation`. |
| 58 |
|
| 59 |
.. note:: |
| 60 |
|
| 61 |
The `reports page`_ contains links to many useful Trac queries, including |
| 62 |
several that are useful for triaging tickets and reviewing patches as |
| 63 |
suggested above. |
| 64 |
|
| 65 |
.. _reports page: https://code.djangoproject.com/wiki/Reports |
| 66 |
|
| 67 |
Sign the Contributor License Agreement |
| 68 |
-------------------------------------- |
| 69 |
|
| 70 |
The code that you write belongs to you or your employer. If your contribution |
| 71 |
is more than one or two lines of code, you need to sign the `CLA`_. See the |
| 72 |
`Contributor License Agreement FAQ`_ for a more thorough explanation. |
| 73 |
|
| 74 |
.. _CLA: https://www.djangoproject.com/foundation/cla/ |
| 75 |
.. _Contributor License Agreement FAQ: https://www.djangoproject.com/foundation/cla/faq/ |
| 76 |
.. _unreviewed ticket: https://code.djangoproject.com/query?status=!closed&stage=Unreviewed |
| 77 |
|
| 78 |
|
| 79 |
Guidelines |
| 80 |
========== |
| 81 |
|
| 82 |
As a newcomer on a large project, it's easy to experience frustration. Here's |
| 83 |
some advice to make your work on Django more useful and rewarding. |
| 84 |
|
| 85 |
Pick a subject area |
| 86 |
------------------- |
| 87 |
|
| 88 |
This should be something that you care about, that you are familiar with or |
| 89 |
that you want to learn about. You don't already have to be an expert on the |
| 90 |
area you want to work on; you become an expert through your ongoing |
| 91 |
contributions to the code. |
| 92 |
|
| 93 |
Analyze tickets' context and history |
| 94 |
------------------------------------ |
| 95 |
|
| 96 |
Trac isn't an absolute; the context is just as important as the words. When |
| 97 |
reading Trac, you need to take into account who says things, and when they were |
| 98 |
said. Support for an idea two years ago doesn't necessarily mean that the idea |
| 99 |
will still have support. You also need to pay attention to who *hasn't* spoken |
| 100 |
-- for example, if an experienced contributor hasn't been recently involved in |
| 101 |
a discussion, then a ticket may not have the support required to get into |
| 102 |
Django. |
| 103 |
|
| 104 |
Start small |
| 105 |
----------- |
| 106 |
|
| 107 |
It's easier to get feedback on a little issue than on a big one. See the |
| 108 |
`easy pickings`_. |
| 109 |
|
| 110 |
Confirm support before engaging in a big task |
| 111 |
--------------------------------------------- |
| 112 |
|
| 113 |
This means getting someone else to confirm that a bug is real before you fix |
| 114 |
the issue, and ensuring that there's consensus on a proposed feature before you |
| 115 |
go implementing it. |
| 116 |
|
| 117 |
Be bold! Leave feedback! |
| 118 |
------------------------ |
| 119 |
|
| 120 |
Sometimes it can be scary to put your opinion out to the world and say "this |
| 121 |
ticket is correct" or "this patch needs work", but it's the only way the |
| 122 |
project moves forward. The contributions of the broad Django community |
| 123 |
ultimately have a much greater impact than that of any one person. We can't do |
| 124 |
it without **you**! |
| 125 |
|
| 126 |
Be cautious when marking things "Ready For Check-in" |
| 127 |
---------------------------------------------------- |
| 128 |
|
| 129 |
If you're really not certain if a ticket is ready, don't mark it as such. Leave |
| 130 |
a comment instead, letting others know your thoughts. If you're mostly certain, |
| 131 |
but not completely certain, you might also try asking on the |
| 132 |
``#contributing-getting-started`` channel in the `Django Discord server`_ to |
| 133 |
see if someone else can confirm your suspicions. |
| 134 |
|
| 135 |
.. _`Django Discord server`: https://chat.djangoproject.com |
| 136 |
|
| 137 |
Wait for feedback, and respond to feedback that you receive |
| 138 |
----------------------------------------------------------- |
| 139 |
|
| 140 |
Focus on one or two tickets, see them through from start to finish, and repeat. |
| 141 |
The shotgun approach of taking on lots of tickets and letting some fall by the |
| 142 |
wayside ends up doing more harm than good. |
| 143 |
|
| 144 |
Be rigorous |
| 145 |
----------- |
| 146 |
|
| 147 |
When we say ":pep:`8`, and must have docs and tests", we mean it. If a patch |
| 148 |
doesn't have docs and tests, there had better be a good reason. Arguments like |
| 149 |
"I couldn't find any existing tests of this feature" don't carry much weight. |
| 150 |
While it may be true, that means you have the extra-important job of writing |
| 151 |
the very first tests for that feature, not that you get a pass from writing |
| 152 |
tests altogether. |
| 153 |
|
| 154 |
Be patient |
| 155 |
---------- |
| 156 |
|
| 157 |
It's not always easy for your ticket or your patch to be reviewed quickly. This |
| 158 |
isn't personal. There are a lot of tickets and pull requests to get through. |
| 159 |
|
| 160 |
Keeping your patch up to date is important. Review the ticket on Trac to ensure |
| 161 |
that the *Needs tests*, *Needs documentation*, and *Patch needs improvement* |
| 162 |
flags are unchecked once you've addressed all review comments. |
| 163 |
|
| 164 |
Remember that Django has an eight-month release cycle, so there's plenty of |
| 165 |
time for your patch to be reviewed. |
| 166 |
|
| 167 |
Finally, a well-timed reminder can help. See :ref:`contributing code FAQ |
| 168 |
<new-contributors-faq>` for ideas here. |
| 169 |
|
| 170 |
.. _easy pickings: https://code.djangoproject.com/query?status=!closed&easy=1 |