/docs/howto/contribute.txt

  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.