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.
|
---|