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