Ticket #14401: contribute.txt

File contribute.txt, 11.2 KB (added by Luke Plant, 13 years ago)

re-wrapped to 80 columns

Line 
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
67What Django's triage stages "really mean"
68-----------------------------------------
69
70Unreviewed
71~~~~~~~~~~
72
73The ticket has not been reviewed by anyone who felt qualified to make a judgment
74about whether the ticket contained a valid issue, a viable feature, or ought to
75be closed for any of the various reasons.
76
77Accepted
78~~~~~~~~
79
80The big grey area! The absolute meaning of "accepted" is that the issue
81described in the ticket is valid and is in some stage of being worked on. Beyond
82that 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
105Design Decision Needed
106~~~~~~~~~~~~~~~~~~~~~~
107
108This stage is for issues which may be contentious, may be backwards
109incompatible, or otherwise involve high-level design decisions. These decisions
110are generally made by the core committers, however that is not a
111requirement. See the FAQ below for "My ticket has been in DDN forever! What
112should I do?"
113
114Ready For Checkin
115~~~~~~~~~~~~~~~~~
116
117The ticket was reviewed by any member of the community other than the person who
118supplied the patch and found to meet all the requirements for a commit-ready
119patch. A core committer now needs to give the patch a final review prior to
120being committed. See the FAQ below for "My ticket has been in RFC forever! What
121should I do?"
122
123Someday/Maybe?
124~~~~~~~~~~~~~~
125
126Generally only used for vague/high-level features or design ideas. These tickets
127are uncommon and overall less useful since they don't describe concrete
128actionable issues.
129
130Fixed on a branch
131~~~~~~~~~~~~~~~~~
132
133Used to indicate that a ticket is resolved as part of a major body of work that
134will eventually be merged to trunk. Tickets in this stage generally don't need
135further work. This may happen in the case of major features/refactors in each
136release cycle, or as part of the annual Google Summer of Code efforts.
137
138Example Trac workflow
139---------------------
140
141Here 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
163Some tickets require much less feedback than this, but then again some tickets
164require much much more.
165
166Advice for new contributors
167===========================
168
169New contributor and not sure what to do? Want to help but just don't know how to
170get 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
252FAQs
253====
254
255**This ticket I care about has been ignored for days/weeks/months! What can I do
256to 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.
Back to Top