|
1 ====================== |
|
2 Contributing to Django |
|
3 ====================== |
|
4 |
|
5 If you think working *with* Django is fun, wait until you start working *on* it. |
|
6 We're passionate about helping Django users make the jump to contributing members |
|
7 of the community, so there are many ways you can help Django's development: |
|
8 |
|
9 * Blog about Django. We syndicate all the Django blogs we know about on |
|
10 the `community page`_; contact jacob@jacobian.org if you've got a blog |
|
11 you'd like to see on that page. |
|
12 |
|
13 * Report bugs and request features in our `ticket tracker`_. Please read |
|
14 `Reporting bugs`_, below, for the details on how we like our bug reports |
|
15 served up. |
|
16 |
|
17 * Submit patches for new and/or fixed behavior. Please read `Submitting |
|
18 patches`_, below, for details on how to submit a patch. |
|
19 |
|
20 * Join the `django-developers`_ mailing list and share your ideas for how |
|
21 to improve Django. We're always open to suggestions, although we're |
|
22 likely to be skeptical of large-scale suggestions without some code to |
|
23 back it up. |
|
24 |
|
25 * Triage patches that have been submitted by other users. Please read |
|
26 `Ticket triage`_ below, for details on the triage process. |
|
27 |
|
28 That's all you need to know if you'd like to join the Django development |
|
29 community. The rest of this document describes the details of how our community |
|
30 works and how it handles bugs, mailing lists, and all the other minutiae of |
|
31 Django development. |
|
32 |
|
33 Reporting bugs |
|
34 ============== |
|
35 |
|
36 Well-written bug reports are *incredibly* helpful. However, there's a certain |
|
37 amount of overhead involved in working with any bug tracking system, so your |
|
38 help in keeping our ticket tracker as useful as possible is appreciated. In |
|
39 particular: |
|
40 |
|
41 * **Do** read the FAQ_ to see if your issue might be a well-known question. |
|
42 |
|
43 * **Do** `search the tracker`_ to see if your issue has already been filed. |
|
44 |
|
45 * **Do** ask on `django-users`_ *first* if you're not sure if what you're |
|
46 seeing is a bug. |
|
47 |
|
48 * **Do** write complete, reproducible, specific bug reports. Include as |
|
49 much information as you possibly can, complete with code snippets, test |
|
50 cases, etc. This means including a clear, concise description of the |
|
51 problem, and a clear set of instructions for replicating the problem. |
|
52 A minimal example that illustrates the bug in a nice small test case |
|
53 is the best possible bug report. |
|
54 |
|
55 * **Don't** use the ticket system to ask support questions. Use the |
|
56 `django-users`_ list, or the `#django`_ IRC channel for that. |
|
57 |
|
58 * **Don't** use the ticket system to make large-scale feature requests. |
|
59 We like to discuss any big changes to Django's core on the `django-developers`_ |
|
60 list before actually working on them. |
|
61 |
|
62 * **Don't** reopen issues that have been marked "wontfix". This mark means |
|
63 that the decision has been made that we can't or won't fix this particular |
|
64 issue. If you're not sure why, please ask on `django-developers`_. |
|
65 |
|
66 * **Don't** use the ticket tracker for lengthy discussions, because they're |
|
67 likely to get lost. If a particular ticket is controversial, please move |
|
68 discussion to `django-developers`_. |
|
69 |
|
70 Reporting security issues |
|
71 ========================= |
|
72 |
|
73 Report security issues to security@djangoproject.com. This is a private list |
|
74 only open to long-time, highly trusted Django developers, and its archives are |
|
75 not publicly readable. |
|
76 |
|
77 In the event of a confirmed vulnerability in Django itself, we will take the |
|
78 following actions: |
|
79 |
|
80 * Acknowledge to the reporter that we've received the report and that a fix |
|
81 is forthcoming. We'll give a rough timeline and ask the reporter to keep |
|
82 the issue confidential until we announce it. |
|
83 |
|
84 * Halt all other development as long as is needed to develop a fix, including |
|
85 patches against the current and two previous releases. |
|
86 |
|
87 * Determine a go-public date for announcing the vulnerability and the fix. |
|
88 To try to mitigate a possible "arms race" between those applying the patch |
|
89 and those trying to exploit the hole, we will not announce security |
|
90 problems immediately. |
|
91 |
|
92 * Pre-notify everyone we know to be running the affected version(s) of |
|
93 Django. We will send these notifications through private e-mail which will |
|
94 include documentation of the vulnerability, links to the relevant patch(es), |
|
95 and a request to keep the vulnerability confidential until the official |
|
96 go-public date. |
|
97 |
|
98 * Publicly announce the vulnerability and the fix on the pre-determined |
|
99 go-public date. This will probably mean a new release of Django, but |
|
100 in some cases it may simply be patches against current releases. |
|
101 |
|
102 Submitting patches |
|
103 ================== |
|
104 |
|
105 We're always grateful for patches to Django's code. Indeed, bug reports with |
|
106 associated patches will get fixed *far* more quickly than those without patches. |
|
107 |
|
108 Patch style |
|
109 ----------- |
|
110 |
|
111 * Make sure your code matches our `coding style`_. |
|
112 |
|
113 * Submit patches in the format returned by the ``svn diff`` command. |
|
114 An exception is for code changes that are described more clearly in plain |
|
115 English than in code. Indentation is the most common example; it's hard to |
|
116 read patches when the only difference in code is that it's indented. |
|
117 |
|
118 * Attach patches to a ticket in the `ticket tracker`_, using the "attach file" |
|
119 button. Please *don't* put the patch in the ticket description or comment |
|
120 unless it's a single line patch. |
|
121 |
|
122 * Name the patch file with a ``.diff`` extension; this will let the ticket |
|
123 tracker apply correct syntax highlighting, which is quite helpful. |
|
124 |
|
125 * Check the "Has patch" box on the ticket details. This will make it |
|
126 obvious that the ticket includes a patch, and it will add the ticket to |
|
127 the `list of tickets with patches`_. |
|
128 |
|
129 * The code required to fix a problem or add a feature is an essential part |
|
130 of a patch, but it is not the only part. A good patch should also include |
|
131 a regression test to validate the behavior that has been fixed (and prevent |
|
132 the problem from arising again). |
|
133 |
|
134 * If the code associated with a patch adds a new feature, or modifies behavior |
|
135 of an existing feature, the patch should also contain documentation. |
|
136 |
|
137 Non-trivial patches |
|
138 ------------------- |
|
139 |
|
140 A "non-trivial" patch is one that is more than a simple bug fix. It's a patch |
|
141 that introduces Django functionality and makes some sort of design decision. |
|
142 |
|
143 If you provide a non-trivial patch, include evidence that alternatives have |
|
144 been discussed on `django-developers`_. If you're not sure whether your patch |
|
145 should be considered non-trivial, just ask. |
|
146 |
|
147 Ticket triage |
|
148 ============= |
|
149 |
|
150 Unfortunately, not all bug reports in the `ticket tracker`_ provide all |
|
151 the `required details`_. A number of tickets have patches, but those patches |
|
152 don't meet all the requirements of a `good patch`_. |
|
153 |
|
154 One way to help out is to *triage* bugs that have been reported by other |
|
155 users. A couple of dedicated volunteers work on this regularly, but more help |
|
156 is always appreciated. |
|
157 |
|
158 Most of the workflow is based around the concept of a ticket's "triage stage". |
|
159 This stage describes where in its lifetime a given ticket is at any time. |
|
160 Along with a handful of flags, this field easily tells us what and who each |
|
161 ticket is waiting on. |
|
162 |
|
163 Since a picture is worth a thousand words, let's start there: |
|
164 |
|
165 .. image:: http://media.djangoproject.com/img/doc/djangotickets.png |
|
166 :height: 451 |
|
167 :width: 590 |
|
168 :alt: Django's ticket workflow |
|
169 |
|
170 We've got two roles here: |
|
171 |
|
172 * Core developers: people with commit access who make the decisions and |
|
173 write the bulk of the code. |
|
174 |
|
175 * Ticket triagers: community members who keep track of tickets, making |
|
176 sure the tickets are always categorized correctly. |
|
177 |
|
178 Second, note the four triage stages: |
|
179 |
|
180 1. A ticket starts as "Unreviewed", meaning that a triager has yet to |
|
181 examine the ticket and move it along. |
|
182 |
|
183 2. "Design decision needed" means "this concept requires a design |
|
184 decision," which should be discussed either in the ticket comments or on |
|
185 django-developers. |
|
186 |
|
187 3. Once a ticket is ruled to be approved for fixing, it's moved into the |
|
188 "Accepted" stage. This stage is where all the real work gets done. |
|
189 |
|
190 4. If a ticket has an associated patch (see below), a triager will review the |
|
191 patch. If the patch is complete, it'll be marked as "ready for checkin" so |
|
192 that a core developer knows to review and check in the patches. |
|
193 |
|
194 The second part of this workflow involves a set of flags the describe what the |
|
195 ticket has or needs in order to be "ready for checkin": |
|
196 |
|
197 "Has patch" |
|
198 This means the ticket has an associated patch_. These will be |
|
199 reviewed to see if the patch is "good". |
|
200 |
|
201 "Needs documentation" |
|
202 This flag is used for tickets with patches that need associated |
|
203 documentation. Complete documentation of features is a prerequisite |
|
204 before we can check a fix into the codebase. |
|
205 |
|
206 "Needs tests" |
|
207 This flags the patch as needing associated unit tests. Again, this is a |
|
208 required part of a valid patch. |
|
209 |
|
210 "Patch needs improvement" |
|
211 This flag means that although the ticket *has* a patch, it's not quite |
|
212 ready for checkin. This could mean the patch no longer applies |
|
213 cleanly, or that the code doesn't live up to our standards. |
|
214 |
|
215 A ticket can be resolved in a number of ways: |
|
216 |
|
217 "fixed" |
|
218 Used by one of the core developers once a patch has been rolled into |
|
219 Django and the issue is fixed. |
|
220 |
|
221 "invalid" |
|
222 Used if the ticket is found to be incorrect or a user error. |
|
223 |
|
224 "wontfix" |
|
225 Used when a core developer decides that this request is not |
|
226 appropriate for consideration in Django. This is usually chosen after |
|
227 discussion in the ``django-developers`` mailing list, and you should |
|
228 feel free to join in when it's something you care about. |
|
229 |
|
230 "duplicate" |
|
231 Used when another ticket covers the same issue. By closing duplicate |
|
232 tickets, we keep all the discussion in one place, which helps everyone. |
|
233 |
|
234 "worksforme" |
|
235 Used when the triage team is unable to replicate the original bug. |
|
236 |
|
237 If you believe that the ticket was closed in error -- because you're |
|
238 still having the issue, or it's popped up somewhere else, or the triagers have |
|
239 -- made a mistake, please reopen the ticket and tell us why. Please do not |
|
240 reopen tickets that have been marked as "wontfix" by core developers. |
|
241 |
|
242 .. _required details: `Reporting bugs`_ |
|
243 .. _good patch: `Patch style`_ |
|
244 .. _patch: `Submitting patches`_ |
|
245 |
|
246 Submitting and maintaining translations |
|
247 ======================================= |
|
248 |
|
249 Various parts of Django, such as the admin site and validator error messages, |
|
250 are internationalized. This means they display different text depending on a |
|
251 user's language setting. |
|
252 |
|
253 These translations are contributed by Django users worldwide. If you find an |
|
254 incorrect translation, or if you'd like to add a language that isn't yet |
|
255 translated, here's what to do: |
|
256 |
|
257 * Join the `Django i18n mailing list`_ and introduce yourself. |
|
258 * Create and submit translations using the methods described in the |
|
259 `i18n documentation`_. |
|
260 |
|
261 .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/ |
|
262 .. _i18n documentation: ../i18n/ |
|
263 |
|
264 Coding style |
|
265 ============ |
|
266 |
|
267 Please follow these coding standards when writing code for inclusion in Django: |
|
268 |
|
269 * Unless otherwise specified, follow `PEP 8`_. |
|
270 |
|
271 * Use four spaces for indentation. |
|
272 |
|
273 * Use underscores, not camelCase, for variable, function and method names |
|
274 (i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``). |
|
275 |
|
276 * Use ``InitialCaps`` for class names (or for factory functions that |
|
277 return classes). |
|
278 |
|
279 * Mark all strings for internationalization; see the `i18n documentation`_ |
|
280 for details. |
|
281 |
|
282 * In Django template code, put one (and only one) space between the curly |
|
283 brackets and the tag contents. |
|
284 |
|
285 Do this:: |
|
286 |
|
287 {{ foo }} |
|
288 |
|
289 Don't do this:: |
|
290 |
|
291 {{foo}} |
|
292 |
|
293 * In Django views, the first parameter in a view function should be called |
|
294 ``request``. |
|
295 |
|
296 Do this:: |
|
297 |
|
298 def my_view(request, foo): |
|
299 # ... |
|
300 |
|
301 Don't do this:: |
|
302 |
|
303 def my_view(req, foo): |
|
304 # ... |
|
305 |
|
306 * Please don't put your name in the code you contribute. Our policy is to |
|
307 keep contributors' names in the ``AUTHORS`` file distributed with Django |
|
308 -- not scattered throughout the codebase itself. Feel free to include a |
|
309 change to the ``AUTHORS`` file in your patch if you make more than a |
|
310 single trivial change. |
|
311 |
|
312 Committing code |
|
313 =============== |
|
314 |
|
315 Please follow these guidelines when committing code to Django's Subversion |
|
316 repository: |
|
317 |
|
318 * For any medium-to-big changes, where "medium-to-big" is according to your |
|
319 judgment, please bring things up on the `django-developers`_ mailing list |
|
320 before making the change. |
|
321 |
|
322 If you bring something up on `django-developers`_ and nobody responds, |
|
323 please don't take that to mean your idea is great and should be |
|
324 implemented immediately because nobody contested it. Django's lead |
|
325 developers don't have a lot of time to read mailing-list discussions |
|
326 immediately, so you may have to wait a couple of days before getting a |
|
327 response. |
|
328 |
|
329 * Write detailed commit messages in the past tense, not present tense. |
|
330 |
|
331 * Good: "Fixed Unicode bug in RSS API." |
|
332 * Bad: "Fixes Unicode bug in RSS API." |
|
333 * Bad: "Fixing Unicode bug in RSS API." |
|
334 |
|
335 * For commits to a branch, prefix the commit message with the branch name. |
|
336 For example: "magic-removal: Added support for mind reading." |
|
337 |
|
338 * Limit commits to the most granular change that makes sense. This means, |
|
339 use frequent small commits rather than infrequent large commits. For |
|
340 example, if implementing feature X requires a small change to library Y, |
|
341 first commit the change to library Y, then commit feature X in a separate |
|
342 commit. This goes a *long way* in helping all core Django developers |
|
343 follow your changes. |
|
344 |
|
345 * If your commit closes a ticket in the Django `ticket tracker`_, begin |
|
346 your commit message with the text "Fixed #abc", where "abc" is the number |
|
347 of the ticket your commit fixes. Example: "Fixed #123 -- Added support |
|
348 for foo". We've rigged Subversion and Trac so that any commit message |
|
349 in that format will automatically close the referenced ticket and post a |
|
350 comment to it with the full commit message. |
|
351 |
|
352 If your commit closes a ticket and is in a branch, use the branch name |
|
353 first, then the "Fixed #abc." For example: |
|
354 "magic-removal: Fixed #123 -- Added whizbang feature." |
|
355 |
|
356 For the curious: We're using a `Trac post-commit hook`_ for this. |
|
357 |
|
358 .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook |
|
359 |
|
360 * If your commit references a ticket in the Django `ticket tracker`_ but |
|
361 does *not* close the ticket, include the phrase "Refs #abc", where "abc" |
|
362 is the number of the ticket your commit references. We've rigged |
|
363 Subversion and Trac so that any commit message in that format will |
|
364 automatically post a comment to the appropriate ticket. |
|
365 |
|
366 Unit tests |
|
367 ========== |
|
368 |
|
369 Django comes with a test suite of its own, in the ``tests`` directory of the |
|
370 Django tarball. It's our policy to make sure all tests pass at all times. |
|
371 |
|
372 The tests cover: |
|
373 |
|
374 * Models and the database API (``tests/modeltests/``). |
|
375 * The cache system (``tests/regressiontests/cache.py``). |
|
376 * The ``django.utils.dateformat`` module (``tests/regressiontests/dateformat/``). |
|
377 * Database typecasts (``tests/regressiontests/db_typecasts/``). |
|
378 * The template system (``tests/regressiontests/templates/`` and |
|
379 ``tests/regressiontests/defaultfilters/``). |
|
380 * ``QueryDict`` objects (``tests/regressiontests/httpwrappers/``). |
|
381 * Markup template tags (``tests/regressiontests/markup/``). |
|
382 |
|
383 We appreciate any and all contributions to the test suite! |
|
384 |
|
385 The Django tests all use the testing infrastructure that ships with Django for |
|
386 testing applications. See `Testing Django applications`_ for an explanation of |
|
387 how to write new tests. |
|
388 |
|
389 .. _Testing Django applications: ../testing/ |
|
390 |
|
391 Running the unit tests |
|
392 ---------------------- |
|
393 |
|
394 To run the tests, ``cd`` to the ``tests/`` directory and type:: |
|
395 |
|
396 ./runtests.py --settings=path.to.django.settings |
|
397 |
|
398 Yes, the unit tests need a settings module, but only for database connection |
|
399 info -- the ``DATABASE_ENGINE``, ``DATABASE_USER`` and ``DATABASE_PASSWORD``. |
|
400 You will also need a ``ROOT_URLCONF`` setting (its value is ignored; it just |
|
401 needs to be present) and a ``SITE_ID`` setting (any integer value will do) in |
|
402 order for all the tests to pass. |
|
403 |
|
404 The unit tests will not touch your existing databases; they create a new |
|
405 database, called ``django_test_db``, which is deleted when the tests are |
|
406 finished. This means your user account needs permission to execute ``CREATE |
|
407 DATABASE``. |
|
408 |
|
409 Requesting features |
|
410 =================== |
|
411 |
|
412 We're always trying to make Django better, and your feature requests are a key |
|
413 part of that. Here are some tips on how to most effectively make a request: |
|
414 |
|
415 * Request the feature on `django-developers`_, not in the ticket tracker; |
|
416 it'll get read more closely if it's on the mailing list. |
|
417 |
|
418 * Describe clearly and concisely what the missing feature is and how you'd |
|
419 like to see it implemented. Include example code (non-functional is OK) |
|
420 if possible. |
|
421 |
|
422 * Explain *why* you'd like the feature. In some cases this is obvious, but |
|
423 since Django is designed to help real developers get real work done, |
|
424 you'll need to explain it, if it isn't obvious why the feature would be |
|
425 useful. |
|
426 |
|
427 As with most open-source projects, code talks. If you are willing to write the |
|
428 code for the feature yourself or if (even better) you've already written it, |
|
429 it's much more likely to be accepted. If it's a large feature that might need |
|
430 multiple developers we're always happy to give you an experimental branch in |
|
431 our repository; see below. |
|
432 |
|
433 Branch policy |
|
434 ============= |
|
435 |
|
436 In general, most development is confined to the trunk, and the trunk |
|
437 is kept stable. People should be able to run production sites against the |
|
438 trunk at any time. |
|
439 |
|
440 Thus, large architectural changes -- that is, changes too large to be |
|
441 encapsulated in a single patch, or changes that need multiple eyes on them -- |
|
442 will have dedicated branches. See, for example, the `i18n branch`_. If you |
|
443 have a change of this nature that you'd like to work on, ask on |
|
444 `django-developers`_ for a branch to be created for you. We'll create a branch |
|
445 for pretty much any kind of experimenting you'd like to do. |
|
446 |
|
447 We will only branch entire copies of the Django tree, even if work is only |
|
448 happening on part of that tree. This makes it painless to switch to a branch. |
|
449 |
|
450 Developers working on a branch should periodically merge changes from the trunk |
|
451 into the branch. Please merge at least once a week. Every time you merge from |
|
452 the trunk, note the merge and revision numbers in the commit message. |
|
453 |
|
454 Once the branch is stable and ready to be merged into the trunk, alert |
|
455 `django-developers`_. |
|
456 |
|
457 After a branch has been merged, it should be considered "dead"; write access to |
|
458 it will be disabled, and old branches will be periodically "trimmed." To keep |
|
459 our SVN wrangling to a minimum, we won't be merging from a given branch into the |
|
460 trunk more than once. |
|
461 |
|
462 Using branches |
|
463 -------------- |
|
464 |
|
465 To use a branch, you'll need to do two things: |
|
466 |
|
467 * Get the branch's code through Subversion. |
|
468 |
|
469 * Point your Python ``site-packages`` directory at the branch's version of |
|
470 the ``django`` package rather than the version you already have |
|
471 installed. |
|
472 |
|
473 Getting the code from Subversion |
|
474 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
475 |
|
476 To get the latest version of a branch's code, check it out using Subversion:: |
|
477 |
|
478 svn co http://code.djangoproject.com/svn/django/branches/<branch>/ |
|
479 |
|
480 ...where ``<branch>`` is the branch's name. See the `list of branch names`_. |
|
481 |
|
482 Alternatively, you can automatically convert an existing directory of the |
|
483 Django source code as long as you've checked it out via Subversion. To do the |
|
484 conversion, execute this command from within your ``django`` directory:: |
|
485 |
|
486 svn switch http://code.djangoproject.com/svn/django/branches/<branch>/ |
|
487 |
|
488 The advantage of using ``svn switch`` instead of ``svn co`` is that the |
|
489 ``switch`` command retains any changes you might have made to your local copy |
|
490 of the code. It attempts to merge those changes into the "switched" code. The |
|
491 disadvantage is that it may cause conflicts with your local changes if the |
|
492 "switched" code has altered the same lines of code. |
|
493 |
|
494 (Note that if you use ``svn switch``, you don't need to point Python at the new |
|
495 version, as explained in the next section.) |
|
496 |
|
497 .. _list of branch names: http://code.djangoproject.com/browser/django/branches |
|
498 |
|
499 Pointing Python at the new Django version |
|
500 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
501 |
|
502 Once you've retrieved the branch's code, you'll need to change your Python |
|
503 ``site-packages`` directory so that it points to the branch version of the |
|
504 ``django`` directory. (The ``site-packages`` directory is somewhere such as |
|
505 ``/usr/lib/python2.4/site-packages`` or |
|
506 ``/usr/local/lib/python2.4/site-packages`` or ``C:\Python\site-packages``.) |
|
507 |
|
508 The simplest way to do this is by renaming the old ``django`` directory to |
|
509 ``django.OLD`` and moving the trunk version of the code into the directory |
|
510 and calling it ``django``. |
|
511 |
|
512 Alternatively, you can use a symlink called ``django`` that points to the |
|
513 location of the branch's ``django`` package. If you want to switch back, just |
|
514 change the symlink to point to the old code. |
|
515 |
|
516 A third option is to use a `path file`_ (``<something>.pth``) which should |
|
517 work on all systems (including Windows, which doesn't have symlinks |
|
518 available). First, make sure there are no files, directories or symlinks named |
|
519 ``django`` in your ``site-packages`` directory. Then create a text file named |
|
520 ``django.pth`` and save it to your ``site-packages`` directory. That file |
|
521 should contain a path to your copy of Django on a single line and optional |
|
522 comments. Here is an example that points to multiple branches. Just uncomment |
|
523 the line for the branch you want to use ('Trunk' in this example) and make |
|
524 sure all other lines are commented:: |
|
525 |
|
526 # Trunk is a svn checkout of: |
|
527 # http://code.djangoproject.com/svn/django/trunk/ |
|
528 # |
|
529 /path/to/trunk |
|
530 |
|
531 # <branch> is a svn checkout of: |
|
532 # http://code.djangoproject.com/svn/django/branches/<branch>/ |
|
533 # |
|
534 #/path/to/<branch> |
|
535 |
|
536 # On windows a path may look like this: |
|
537 # C:/path/to/<branch> |
|
538 |
|
539 If you're using Django 0.95 or earlier and installed it using |
|
540 ``python setup.py install``, you'll have a directory called something like |
|
541 ``Django-0.95-py2.4.egg`` instead of ``django``. In this case, edit the file |
|
542 ``setuptools.pth`` and remove the line that references the Django ``.egg`` |
|
543 file. Then copy the branch's version of the ``django`` directory into |
|
544 ``site-packages``. |
|
545 |
|
546 .. _path file: http://docs.python.org/lib/module-site.html |
|
547 |
|
548 Official releases |
|
549 ================= |
|
550 |
|
551 Django's release numbering works as follows: |
|
552 |
|
553 * Versions are numbered in the form ``A.B`` or ``A.B.C``. |
|
554 |
|
555 * ``A`` is the major version number, which is only incremented for major |
|
556 changes to Django, and these changes are not necessarily |
|
557 backwards-compatible. That is, code you wrote for Django 6.0 may break |
|
558 when we release Django 7.0. |
|
559 |
|
560 * ``B`` is the minor version number, which is incremented for large yet |
|
561 backwards compatible changes. Code written for Django 6.4 will continue |
|
562 to work under Django 6.5. |
|
563 |
|
564 A minor release may deprecate certain features in previous releases. If a |
|
565 feature in version ``A.B`` is deprecated, it will continue to work in |
|
566 version ``A.B+1``. In version ``A.B+2``, use of the feature will raise a |
|
567 ``PendingDeprecationWarning`` but will continue to work. Version |
|
568 ``A.B+3`` will remove the feature entirely. Major point releases will |
|
569 always remove deprecated features immediately. |
|
570 |
|
571 * ``C`` is the micro version number which, is incremented for bug and |
|
572 security fixes. A new micro-release will always be 100% |
|
573 backwards-compatible with the previous micro-release. |
|
574 |
|
575 * In some cases, we'll make release candidate releases. These are of the |
|
576 form ``A.BrcN``, which means the ``Nth`` candidate release of version |
|
577 ``A.B``. |
|
578 |
|
579 An exception to this version numbering scheme is the pre-1.0 Django code. |
|
580 There's no guarantee of backwards-compatibility until the 1.0 release. |
|
581 |
|
582 In Subversion, each Django release will be tagged under `tags/releases`_. If |
|
583 it's necessary to release a bug fix release or a security release that doesn't |
|
584 come from the trunk, we'll copy that tag to ``branches/releases`` to make the |
|
585 bug fix release. |
|
586 |
|
587 Deciding on features |
|
588 ==================== |
|
589 |
|
590 Once a feature's been requested and discussed, eventually we'll have a decision |
|
591 about whether to include the feature or drop it. |
|
592 |
|
593 Whenever possible, we strive for a rough consensus. To that end, we'll often |
|
594 have informal votes on `django-developers`_ about a feature. In these votes we |
|
595 follow the voting style invented by Apache and used on Python itself, where |
|
596 votes are given as +1, +0, -0, or -1. Roughly translated, these votes mean: |
|
597 |
|
598 * +1: "I love the idea and I'm strongly committed to it." |
|
599 |
|
600 * +0: "Sounds OK to me." |
|
601 |
|
602 * -0: "I'm not thrilled, but I won't stand in the way." |
|
603 |
|
604 * -1: "I strongly disagree and would be very unhappy to see the idea turn |
|
605 into reality." |
|
606 |
|
607 Although these votes on django-developers are informal, they'll be taken very |
|
608 seriously. After a suitable voting period, if an obvious consensus arises |
|
609 we'll follow the votes. |
|
610 |
|
611 However, consensus is not always possible. Tough decisions will be discussed by |
|
612 all full committers and finally decided by the Benevolent Dictators for Life, |
|
613 Adrian and Jacob. |
|
614 |
|
615 Commit access |
|
616 ============= |
|
617 |
|
618 Django has two types of committers: |
|
619 |
|
620 Full committers |
|
621 These are people who have a long history of contributions to Django's |
|
622 codebase, a solid track record of being polite and helpful on the mailing |
|
623 lists, and a proven desire to dedicate serious time to Django's development. |
|
624 |
|
625 The bar is very high for full commit access. It will only be granted by |
|
626 unanimous approval of all existing full committers, and the decision will err |
|
627 on the side of rejection. |
|
628 |
|
629 Partial committers |
|
630 These are people who are "domain experts." They have direct check-in access |
|
631 to the subsystems that fall under their jurisdiction, and they're given a |
|
632 formal vote in questions that involve their subsystems. This type of access |
|
633 is likely to be given to someone who contributes a large subframework to |
|
634 Django and wants to continue to maintain it. |
|
635 |
|
636 Like full committers, partial commit access is by unanimous approval of all |
|
637 full committers (and any other partial committers in the same area). |
|
638 However, the bar is set lower; proven expertise in the area in question is |
|
639 likely to be sufficient. |
|
640 |
|
641 To request commit access, please contact an existing committer privately. Public |
|
642 requests for commit access are potential flame-war starters, and will be ignored. |
|
643 |
|
644 .. _community page: http://www.djangoproject.com/community/ |
|
645 .. _ticket tracker: http://code.djangoproject.com/newticket |
|
646 .. _django-developers: http://groups.google.com/group/django-developers |
|
647 .. _FAQ: http://www.djangoproject.com/documentation/faq/ |
|
648 .. _search the tracker: http://code.djangoproject.com/search |
|
649 .. _django-users: http://groups.google.com/group/django-users |
|
650 .. _`#django`: irc://irc.freenode.net/django |
|
651 .. _list of tickets with patches: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority |
|
652 .. _PEP 8: http://www.python.org/peps/pep-0008.html |
|
653 .. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n |
|
654 .. _`tags/releases`: http://code.djangoproject.com/browser/django/tags/releases |