| 1 | ===========================
|
|---|
| 2 | How to contribute to Django
|
|---|
| 3 | ===========================
|
|---|
| 4 |
|
|---|
| 5 | Django is developed 100% by the community, and the more people that are actively
|
|---|
| 6 | involved in the code the better Django will be. We recognize that contributing
|
|---|
| 7 | to Django can be daunting at first and sometimes confusing even to
|
|---|
| 8 | veterans. While we have our official "Contributing to Django" documentation
|
|---|
| 9 | which spells out the technical details of triaging tickets and submitting
|
|---|
| 10 | patches, it leaves a lot of room for interpretation. This guide aims to offer
|
|---|
| 11 | more general advice on issues such as how to interpret the various stages and
|
|---|
| 12 | flags in Trac, and how new contributors can get started.
|
|---|
| 13 |
|
|---|
| 14 | .. seealso::
|
|---|
| 15 |
|
|---|
| 16 | This guide is meant to answer the most common questions about
|
|---|
| 17 | contributing to Django, however it is no substitute for the
|
|---|
| 18 | :doc:`/internals/contributing` reference. Please make sure to
|
|---|
| 19 | read that document to understand the specific details
|
|---|
| 20 | involved in reporting issues and submitting patches.
|
|---|
| 21 |
|
|---|
| 22 | .. _the-spirit-of-contributing:
|
|---|
| 23 |
|
|---|
| 24 | "The Spirit of Contributing"
|
|---|
| 25 | ============================
|
|---|
| 26 |
|
|---|
| 27 | Django uses Trac_ for managing our progress, and Trac is a community-tended
|
|---|
| 28 | garden of the bugs people have found and the features people would like to see
|
|---|
| 29 | added. As in any garden, sometimes there are weeds to be pulled and sometimes
|
|---|
| 30 | there are flowers and vegetables that need picking. We need your help to sort
|
|---|
| 31 | out one from the other, and in the end we all benefit together.
|
|---|
| 32 |
|
|---|
| 33 | Like all gardens, we can aspire to perfection but in reality there's no such
|
|---|
| 34 | thing. Even in the most pristine garden there are still snails and insects. In a
|
|---|
| 35 | community garden there are also helpful people who--with the best of
|
|---|
| 36 | intentions--fertilize the weeds and poison the roses. It's the job of the
|
|---|
| 37 | community as a whole to self-manage, keep the problems to a minimum, and educate
|
|---|
| 38 | those coming into the community so that they can become valuable contributing
|
|---|
| 39 | members.
|
|---|
| 40 |
|
|---|
| 41 | Similarly, while we aim for Trac to be a perfect representation of the state of
|
|---|
| 42 | Django's progress, we acknowledge that this simply will not happen. By
|
|---|
| 43 | distributing the load of Trac maintenance to the community, we accept that there
|
|---|
| 44 | will be mistakes. Trac is "mostly accurate", and we give allowances for the fact
|
|---|
| 45 | that sometimes it will be wrong. That's okay. We're perfectionists with
|
|---|
| 46 | deadlines.
|
|---|
| 47 |
|
|---|
| 48 | We rely on the community to keep participating, keep tickets as accurate as
|
|---|
| 49 | possible, and raise issues for discussion on our mailing lists when there is
|
|---|
| 50 | confusion or disagreement.
|
|---|
| 51 |
|
|---|
| 52 | Django is a community project, and every contribution helps. We can't do this
|
|---|
| 53 | without YOU!
|
|---|
| 54 |
|
|---|
| 55 | .. _Trac: http://code.djangoproject.com/
|
|---|
| 56 |
|
|---|
| 57 | Understanding Trac
|
|---|
| 58 | ==================
|
|---|
| 59 |
|
|---|
| 60 | Trac is Django's sole official issue tracker. All known bugs, desired features
|
|---|
| 61 | and ideas for changes are logged there.
|
|---|
| 62 |
|
|---|
| 63 | However, Trac can be quite confusing even to veteran contributors. Having to
|
|---|
| 64 | look at both flags and triage stages isn't immediately obvious, and the stages
|
|---|
| 65 | themselves can be misinterpreted.
|
|---|
| 66 |
|
|---|
| 67 | What Django's triage stages "really mean"
|
|---|
| 68 | -----------------------------------------
|
|---|
| 69 |
|
|---|
| 70 | Unreviewed
|
|---|
| 71 | ~~~~~~~~~~
|
|---|
| 72 |
|
|---|
| 73 | The ticket has not been reviewed by anyone who felt qualified to make a judgment
|
|---|
| 74 | about whether the ticket contained a valid issue, a viable feature, or ought to
|
|---|
| 75 | be closed for any of the various reasons.
|
|---|
| 76 |
|
|---|
| 77 | Accepted
|
|---|
| 78 | ~~~~~~~~
|
|---|
| 79 |
|
|---|
| 80 | The big grey area! The absolute meaning of "accepted" is that the issue
|
|---|
| 81 | described in the ticket is valid and is in some stage of being worked on. Beyond
|
|---|
| 82 | that there are several considerations
|
|---|
| 83 |
|
|---|
| 84 |
|
|---|
| 85 | * **Accepted + No Flags**
|
|---|
| 86 |
|
|---|
| 87 | The ticket is valid, but no one has submitted a patch for it yet. Often this
|
|---|
| 88 | means you could safely start writing a patch for it.
|
|---|
| 89 |
|
|---|
| 90 | * **Accepted + Has Patch**
|
|---|
| 91 |
|
|---|
| 92 | The ticket is waiting for people to review the supplied patch. This means
|
|---|
| 93 | downloading the patch and trying it out, verifying that it contains tests and
|
|---|
| 94 | docs, running the test suite with the included patch, and leaving feedback on
|
|---|
| 95 | the ticket.
|
|---|
| 96 |
|
|---|
| 97 |
|
|---|
| 98 | * **Accepted + Has Patch + (any other flag)**
|
|---|
| 99 |
|
|---|
| 100 | This means the ticket has been reviewed, and has been found to need further
|
|---|
| 101 | work. "Needs tests" and "Needs documentation" are self-explanatory. "Patch
|
|---|
| 102 | needs improvement" will generally be accompanied by a comment on the ticket
|
|---|
| 103 | explaining what is needed to improve the code.
|
|---|
| 104 |
|
|---|
| 105 | Design Decision Needed
|
|---|
| 106 | ~~~~~~~~~~~~~~~~~~~~~~
|
|---|
| 107 |
|
|---|
| 108 | This stage is for issues which may be contentious, may be backwards
|
|---|
| 109 | incompatible, or otherwise involve high-level design decisions. These decisions
|
|---|
| 110 | are generally made by the core committers, however that is not a
|
|---|
| 111 | requirement. See the FAQ below for "My ticket has been in DDN forever! What
|
|---|
| 112 | should I do?"
|
|---|
| 113 |
|
|---|
| 114 | Ready For Checkin
|
|---|
| 115 | ~~~~~~~~~~~~~~~~~
|
|---|
| 116 |
|
|---|
| 117 | The ticket was reviewed by any member of the community other than the person who
|
|---|
| 118 | supplied the patch and found to meet all the requirements for a commit-ready
|
|---|
| 119 | patch. A core committer now needs to give the patch a final review prior to
|
|---|
| 120 | being committed. See the FAQ below for "My ticket has been in RFC forever! What
|
|---|
| 121 | should I do?"
|
|---|
| 122 |
|
|---|
| 123 | Someday/Maybe?
|
|---|
| 124 | ~~~~~~~~~~~~~~
|
|---|
| 125 |
|
|---|
| 126 | Generally only used for vague/high-level features or design ideas. These tickets
|
|---|
| 127 | are uncommon and overall less useful since they don't describe concrete
|
|---|
| 128 | actionable issues.
|
|---|
| 129 |
|
|---|
| 130 | Fixed on a branch
|
|---|
| 131 | ~~~~~~~~~~~~~~~~~
|
|---|
| 132 |
|
|---|
| 133 | Used to indicate that a ticket is resolved as part of a major body of work that
|
|---|
| 134 | will eventually be merged to trunk. Tickets in this stage generally don't need
|
|---|
| 135 | further work. This may happen in the case of major features/refactors in each
|
|---|
| 136 | release cycle, or as part of the annual Google Summer of Code efforts.
|
|---|
| 137 |
|
|---|
| 138 | Example Trac workflow
|
|---|
| 139 | ---------------------
|
|---|
| 140 |
|
|---|
| 141 | Here we see the life-cycle of an average ticket:
|
|---|
| 142 |
|
|---|
| 143 | * Alice creates a ticket, and uploads an incomplete patch (no tests, incorrect
|
|---|
| 144 | implementation).
|
|---|
| 145 |
|
|---|
| 146 | * Bob reviews the patch, marks it "Accepted", "needs tests", and "patch needs
|
|---|
| 147 | improvement", and leaves a comment telling Alice how the patch could be
|
|---|
| 148 | improved.
|
|---|
| 149 |
|
|---|
| 150 | * Alice updates the patch, adding tests (but not changing the
|
|---|
| 151 | implementation). She removes the two flags.
|
|---|
| 152 |
|
|---|
| 153 | * Charlie reviews the patch and resets the "patch needs improvement" flag with
|
|---|
| 154 | another comment about improving the implementation.
|
|---|
| 155 |
|
|---|
| 156 | * Alice updates the patch, fixing the implementation. She removes the "patch
|
|---|
| 157 | needs improvement" flag.
|
|---|
| 158 |
|
|---|
| 159 | * Daisy reviews the patch, and marks it RFC.
|
|---|
| 160 |
|
|---|
| 161 | * Jacob reviews the RFC patch, applies it to his checkout, and commits it.
|
|---|
| 162 |
|
|---|
| 163 | Some tickets require much less feedback than this, but then again some tickets
|
|---|
| 164 | require much much more.
|
|---|
| 165 |
|
|---|
| 166 | Advice for new contributors
|
|---|
| 167 | ===========================
|
|---|
| 168 |
|
|---|
| 169 | New contributor and not sure what to do? Want to help but just don't know how to
|
|---|
| 170 | get started? This is the section for you.
|
|---|
| 171 |
|
|---|
| 172 | * **Pick a subject area that you care about, that you are familiar with, or that
|
|---|
| 173 | you want to learn about.**
|
|---|
| 174 |
|
|---|
| 175 | You don't already have to be an expert on the area you want to work on; you
|
|---|
| 176 | become an expert through your ongoing contributions to the code.
|
|---|
| 177 |
|
|---|
| 178 | * **Triage tickets.**
|
|---|
| 179 |
|
|---|
| 180 | If a ticket is unreviewed and reports a bug, try and duplicate it. If you can
|
|---|
| 181 | duplicate it and it seems valid, make a note that you confirmed the bug and
|
|---|
| 182 | accept the ticket. Make sure the ticket is filed under the correct component
|
|---|
| 183 | area. Consider writing a patch that adds a test for the bug's behavior, even
|
|---|
| 184 | if you don't fix the bug itself.
|
|---|
| 185 |
|
|---|
| 186 | * **Look for tickets that are accepted and review patches to build familiarity
|
|---|
| 187 | with the codebase and the process.**
|
|---|
| 188 |
|
|---|
| 189 | Mark the appropriate flags if a patch needs docs or tests. Look through the
|
|---|
| 190 | changes a patch makes, and keep an eye out for syntax that is incompatible
|
|---|
| 191 | with older but still supported versions of Python. Run the tests and make sure
|
|---|
| 192 | they pass on your system. Where possible and relevant, try them out on a
|
|---|
| 193 | database other than SQLite. Leave comments and feedback!
|
|---|
| 194 |
|
|---|
| 195 | * **Keep old patches up to date.**
|
|---|
| 196 |
|
|---|
| 197 | Oftentimes the codebase will change between a patch being submitted and the
|
|---|
| 198 | time it gets reviewed. Make sure it still applies cleanly and functions as
|
|---|
| 199 | expected. Simply updating a patch is both useful and important!
|
|---|
| 200 |
|
|---|
| 201 | * **Trac isn't an absolute; the context is just as important as the words.**
|
|---|
| 202 |
|
|---|
| 203 | When reading Trac, you need to take into account who says things, and when
|
|---|
| 204 | they were said. Support for an idea two years ago doesn't necessarily mean
|
|---|
| 205 | that the idea will still have support. You also need to pay attention to who
|
|---|
| 206 | *hasn't* spoken -- for example, if a core team member hasn't been recently
|
|---|
| 207 | involved in a discussion, then a ticket may not have the support required to
|
|---|
| 208 | get into trunk.
|
|---|
| 209 |
|
|---|
| 210 | * **Start small.**
|
|---|
| 211 |
|
|---|
| 212 | It's easier to get feedback on a little issue than on a big one.
|
|---|
| 213 |
|
|---|
| 214 | * **If you're going to engage in a big task, make sure that your idea has
|
|---|
| 215 | support first.**
|
|---|
| 216 |
|
|---|
| 217 | This means getting someone else to confirm that a bug is real before you fix
|
|---|
| 218 | the issue, and ensuring that the core team supports a proposed feature before
|
|---|
| 219 | you go implementing it.
|
|---|
| 220 |
|
|---|
| 221 | * **Be bold! Leave feedback!**
|
|---|
| 222 |
|
|---|
| 223 | Sometimes it can be scary to put your opinion out to the world and say "this
|
|---|
| 224 | ticket is correct" or "this patch needs work", but it's the only way the
|
|---|
| 225 | project moves forward. The contributions of the broad Django community
|
|---|
| 226 | ultimately have a much greater impact than that of the core developers. We
|
|---|
| 227 | can't do it without YOU!
|
|---|
| 228 |
|
|---|
| 229 | * **Err on the side of caution when marking things Ready For Check-in.**
|
|---|
| 230 |
|
|---|
| 231 | If you're really not certain if a ticket is ready, don't mark it as
|
|---|
| 232 | such. Leave a comment instead, letting others know your thoughts. If you're
|
|---|
| 233 | mostly certain, but not completely certain, you might also try asking on IRC
|
|---|
| 234 | to see if someone else can confirm your suspicions.
|
|---|
| 235 |
|
|---|
| 236 | * **Wait for feedback, and respond to feedback that you receive.**
|
|---|
| 237 |
|
|---|
| 238 | Focus on one or two tickets, see them through from start to finish, and
|
|---|
| 239 | repeat. The shotgun approach of taking on lots of tickets and letting some
|
|---|
| 240 | fall by the wayside ends up doing more harm than good.
|
|---|
| 241 |
|
|---|
| 242 | * **Be rigorous.**
|
|---|
| 243 |
|
|---|
| 244 | When we say ":pep:`8`, and must have docs and tests", we mean it. If a patch
|
|---|
| 245 | doesn't have docs and tests, there had better be a good reason. Arguments like
|
|---|
| 246 | "I couldn't find any existing tests of this feature" don't carry much
|
|---|
| 247 | weight--while it may be true, that means you have the extra-important job of
|
|---|
| 248 | writing the very first tests for that feature, not that you get a pass from
|
|---|
| 249 | writing tests altogether.
|
|---|
| 250 |
|
|---|
| 251 |
|
|---|
| 252 | FAQs
|
|---|
| 253 | ====
|
|---|
| 254 |
|
|---|
| 255 | **This ticket I care about has been ignored for days/weeks/months! What can I do
|
|---|
| 256 | to get it committed?**
|
|---|
| 257 |
|
|---|
| 258 | * First off, it's not personal. Django is entirely developed by volunteers (even
|
|---|
| 259 | the core devs), and sometimes folks just don't have time. The best thing to do
|
|---|
| 260 | is to send a gentle reminder to the Django Developers mailing list asking for
|
|---|
| 261 | review on the ticket, or to bring it up in the #django-dev IRC channel.
|
|---|
| 262 |
|
|---|
| 263 |
|
|---|
| 264 | **I'm sure my ticket is absolutely 100% perfect, can I mark it as RFC myself?**
|
|---|
| 265 |
|
|---|
| 266 | * Short answer: No. It's always better to get another set of eyes on a
|
|---|
| 267 | ticket. If you're having trouble getting that second set of eyes, see question
|
|---|
| 268 | 1, above.
|
|---|
| 269 |
|
|---|
| 270 |
|
|---|
| 271 | **My ticket has been in DDN forever! What should I do?**
|
|---|
| 272 |
|
|---|
| 273 | * Design Decision Needed requires consensus about the right solution. At the
|
|---|
| 274 | very least it needs consensus among the core developers, and ideally it has
|
|---|
| 275 | consensus from the community as well. The best way to accomplish this is to
|
|---|
| 276 | start a thread on the Django Developers mailing list, and for very complex
|
|---|
| 277 | issues to start a wiki page summarizing the problem and the possible
|
|---|
| 278 | solutions.
|
|---|