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:
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.
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
17
* Submit patches for new and/or fixed behavior. Please read `Submitting
18
patches`_, below, for details on how to submit a patch.
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
25
* Triage patches that have been submitted by other users. Please read
26
`Ticket triage`_ below, for details on the triage process.
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
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
41
* **Do** read the FAQ_ to see if your issue might be a well-known question.
43
* **Do** `search the tracker`_ to see if your issue has already been filed.
45
* **Do** ask on `django-users`_ *first* if you're not sure if what you're
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.
55
* **Don't** use the ticket system to ask support questions. Use the
56
`django-users`_ list, or the `#django`_ IRC channel for that.
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.
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`_.
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`_.
70
Reporting security issues
71
=========================
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.
77
In the event of a confirmed vulnerability in Django itself, we will take the
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.
84
* Halt all other development as long as is needed to develop a fix, including
85
patches against the current and two previous releases.
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
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
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.
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.
111
* Make sure your code matches our `coding style`_.
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.
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.
122
* Name the patch file with a ``.diff`` extension; this will let the ticket
123
tracker apply correct syntax highlighting, which is quite helpful.
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`_.
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).
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.
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.
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.
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`_.
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.
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.
163
Since a picture is worth a thousand words, let's start there:
165
.. image:: http://media.djangoproject.com/img/doc/djangotickets.png
168
:alt: Django's ticket workflow
170
We've got two roles here:
172
* Core developers: people with commit access who make the decisions and
173
write the bulk of the code.
175
* Ticket triagers: community members who keep track of tickets, making
176
sure the tickets are always categorized correctly.
178
Second, note the four triage stages:
180
1. A ticket starts as "Unreviewed", meaning that a triager has yet to
181
examine the ticket and move it along.
183
2. "Design decision needed" means "this concept requires a design
184
decision," which should be discussed either in the ticket comments or on
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.
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.
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":
198
This means the ticket has an associated patch_. These will be
199
reviewed to see if the patch is "good".
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.
207
This flags the patch as needing associated unit tests. Again, this is a
208
required part of a valid patch.
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.
215
A ticket can be resolved in a number of ways:
218
Used by one of the core developers once a patch has been rolled into
219
Django and the issue is fixed.
222
Used if the ticket is found to be incorrect or a user error.
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.
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.
235
Used when the triage team is unable to replicate the original bug.
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
reopen tickets that have been marked as "wontfix" by core developers.
241
.. _required details: `Reporting bugs`_
242
.. _good patch: `Patch style`_
243
.. _patch: `Submitting patches`_
245
Submitting and maintaining translations
246
=======================================
248
Various parts of Django, such as the admin site and validator error messages,
249
are internationalized. This means they display different text depending on a
250
user's language setting.
252
These translations are contributed by Django users worldwide. If you find an
253
incorrect translation, or if you'd like to add a language that isn't yet
254
translated, here's what to do:
256
* Join the `Django i18n mailing list`_ and introduce yourself.
257
* Create and submit translations using the methods described in the
258
`i18n documentation`_.
260
.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
261
.. _i18n documentation: ../i18n/
266
Please follow these coding standards when writing code for inclusion in Django:
268
* Unless otherwise specified, follow `PEP 8`_.
270
* Use four spaces for indentation.
272
* Use underscores, not camelCase, for variable, function and method names
273
(i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``).
275
* Use ``InitialCaps`` for class names (or for factory functions that
278
* Mark all strings for internationalization; see the `i18n documentation`_
281
* In Django template code, put one (and only one) space between the curly
282
brackets and the tag contents.
292
* In Django views, the first parameter in a view function should be called
297
def my_view(request, foo):
302
def my_view(req, foo):
305
* Please don't put your name in the code you contribute. Our policy is to
306
keep contributors' names in the ``AUTHORS`` file distributed with Django
307
-- not scattered throughout the codebase itself. Feel free to include a
308
change to the ``AUTHORS`` file in your patch if you make more than a
309
single trivial change.
314
Please follow these guidelines when committing code to Django's Subversion
317
* For any medium-to-big changes, where "medium-to-big" is according to your
318
judgment, please bring things up on the `django-developers`_ mailing list
319
before making the change.
321
If you bring something up on `django-developers`_ and nobody responds,
322
please don't take that to mean your idea is great and should be
323
implemented immediately because nobody contested it. Django's lead
324
developers don't have a lot of time to read mailing-list discussions
325
immediately, so you may have to wait a couple of days before getting a
328
* Write detailed commit messages in the past tense, not present tense.
330
* Good: "Fixed Unicode bug in RSS API."
331
* Bad: "Fixes Unicode bug in RSS API."
332
* Bad: "Fixing Unicode bug in RSS API."
334
* For commits to a branch, prefix the commit message with the branch name.
335
For example: "magic-removal: Added support for mind reading."
337
* Limit commits to the most granular change that makes sense. This means,
338
use frequent small commits rather than infrequent large commits. For
339
example, if implementing feature X requires a small change to library Y,
340
first commit the change to library Y, then commit feature X in a separate
341
commit. This goes a *long way* in helping all core Django developers
344
* If your commit closes a ticket in the Django `ticket tracker`_, begin
345
your commit message with the text "Fixed #abc", where "abc" is the number
346
of the ticket your commit fixes. Example: "Fixed #123 -- Added support
347
for foo". We've rigged Subversion and Trac so that any commit message
348
in that format will automatically close the referenced ticket and post a
349
comment to it with the full commit message.
351
If your commit closes a ticket and is in a branch, use the branch name
352
first, then the "Fixed #abc." For example:
353
"magic-removal: Fixed #123 -- Added whizbang feature."
355
For the curious: We're using a `Trac post-commit hook`_ for this.
357
.. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook
359
* If your commit references a ticket in the Django `ticket tracker`_ but
360
does *not* close the ticket, include the phrase "Refs #abc", where "abc"
361
is the number of the ticket your commit references. We've rigged
362
Subversion and Trac so that any commit message in that format will
363
automatically post a comment to the appropriate ticket.
368
Django comes with a test suite of its own, in the ``tests`` directory of the
369
Django tarball. It's our policy to make sure all tests pass at all times.
373
* Models and the database API (``tests/modeltests/``).
374
* The cache system (``tests/regressiontests/cache.py``).
375
* The ``django.utils.dateformat`` module (``tests/regressiontests/dateformat/``).
376
* Database typecasts (``tests/regressiontests/db_typecasts/``).
377
* The template system (``tests/regressiontests/templates/`` and
378
``tests/regressiontests/defaultfilters/``).
379
* ``QueryDict`` objects (``tests/regressiontests/httpwrappers/``).
380
* Markup template tags (``tests/regressiontests/markup/``).
382
We appreciate any and all contributions to the test suite!
384
The Django tests all use the testing infrastructure that ships with Django for
385
testing applications. See `Testing Django applications`_ for an explanation of
386
how to write new tests.
388
.. _Testing Django applications: ../testing/
390
Running the unit tests
391
----------------------
393
To run the tests, ``cd`` to the ``tests/`` directory and type::
395
./runtests.py --settings=path.to.django.settings
397
Yes, the unit tests need a settings module, but only for database connection
398
info -- the ``DATABASE_ENGINE``, ``DATABASE_USER`` and ``DATABASE_PASSWORD``.
399
You will also need a ``ROOT_URLCONF`` setting (its value is ignored; it just
400
needs to be present) and a ``SITE_ID`` setting (any integer value will do) in
401
order for all the tests to pass.
403
The unit tests will not touch your existing databases; they create a new
404
database, called ``django_test_db``, which is deleted when the tests are
405
finished. This means your user account needs permission to execute ``CREATE
411
We're always trying to make Django better, and your feature requests are a key
412
part of that. Here are some tips on how to most effectively make a request:
414
* Request the feature on `django-developers`_, not in the ticket tracker;
415
it'll get read more closely if it's on the mailing list.
417
* Describe clearly and concisely what the missing feature is and how you'd
418
like to see it implemented. Include example code (non-functional is OK)
421
* Explain *why* you'd like the feature. In some cases this is obvious, but
422
since Django is designed to help real developers get real work done,
423
you'll need to explain it, if it isn't obvious why the feature would be
426
As with most open-source projects, code talks. If you are willing to write the
427
code for the feature yourself or if (even better) you've already written it,
428
it's much more likely to be accepted. If it's a large feature that might need
429
multiple developers we're always happy to give you an experimental branch in
430
our repository; see below.
435
In general, most development is confined to the trunk, and the trunk
436
is kept stable. People should be able to run production sites against the
439
Thus, large architectural changes -- that is, changes too large to be
440
encapsulated in a single patch, or changes that need multiple eyes on them --
441
will have dedicated branches. See, for example, the `i18n branch`_. If you
442
have a change of this nature that you'd like to work on, ask on
443
`django-developers`_ for a branch to be created for you. We'll create a branch
444
for pretty much any kind of experimenting you'd like to do.
446
We will only branch entire copies of the Django tree, even if work is only
447
happening on part of that tree. This makes it painless to switch to a branch.
449
Developers working on a branch should periodically merge changes from the trunk
450
into the branch. Please merge at least once a week. Every time you merge from
451
the trunk, note the merge and revision numbers in the commit message.
453
Once the branch is stable and ready to be merged into the trunk, alert
454
`django-developers`_.
456
After a branch has been merged, it should be considered "dead"; write access to
457
it will be disabled, and old branches will be periodically "trimmed." To keep
458
our SVN wrangling to a minimum, we won't be merging from a given branch into the
459
trunk more than once.
464
To use a branch, you'll need to do two things:
466
* Get the branch's code through Subversion.
468
* Point your Python ``site-packages`` directory at the branch's version of
469
the ``django`` package rather than the version you already have
472
Getting the code from Subversion
473
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
475
To get the latest version of a branch's code, check it out using Subversion::
477
svn co http://code.djangoproject.com/svn/django/branches/<branch>/
479
...where ``<branch>`` is the branch's name. See the `list of branch names`_.
481
Alternatively, you can automatically convert an existing directory of the
482
Django source code as long as you've checked it out via Subversion. To do the
483
conversion, execute this command from within your ``django`` directory::
485
svn switch http://code.djangoproject.com/svn/django/branches/<branch>/
487
The advantage of using ``svn switch`` instead of ``svn co`` is that the
488
``switch`` command retains any changes you might have made to your local copy
489
of the code. It attempts to merge those changes into the "switched" code. The
490
disadvantage is that it may cause conflicts with your local changes if the
491
"switched" code has altered the same lines of code.
493
(Note that if you use ``svn switch``, you don't need to point Python at the new
494
version, as explained in the next section.)
496
.. _list of branch names: http://code.djangoproject.com/browser/django/branches
498
Pointing Python at the new Django version
499
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
501
Once you've retrieved the branch's code, you'll need to change your Python
502
``site-packages`` directory so that it points to the branch version of the
503
``django`` directory. (The ``site-packages`` directory is somewhere such as
504
``/usr/lib/python2.4/site-packages`` or
505
``/usr/local/lib/python2.4/site-packages`` or ``C:\Python\site-packages``.)
507
The simplest way to do this is by renaming the old ``django`` directory to
508
``django.OLD`` and moving the trunk version of the code into the directory
509
and calling it ``django``.
511
Alternatively, you can use a symlink called ``django`` that points to the
512
location of the branch's ``django`` package. If you want to switch back, just
513
change the symlink to point to the old code.
515
A third option is to use a `path file`_ (``<something>.pth``) which should
516
work on all systems (including Windows, which doesn't have symlinks
517
available). First, make sure there are no files, directories or symlinks named
518
``django`` in your ``site-packages`` directory. Then create a text file named
519
``django.pth`` and save it to your ``site-packages`` directory. That file
520
should contain a path to your copy of Django on a single line and optional
521
comments. Here is an example that points to multiple branches. Just uncomment
522
the line for the branch you want to use ('Trunk' in this example) and make
523
sure all other lines are commented::
525
# Trunk is a svn checkout of:
526
# http://code.djangoproject.com/svn/django/trunk/
530
# <branch> is a svn checkout of:
531
# http://code.djangoproject.com/svn/django/branches/<branch>/
535
# On windows a path may look like this:
536
# C:/path/to/<branch>
538
If you're using Django 0.95 or earlier and installed it using
539
``python setup.py install``, you'll have a directory called something like
540
``Django-0.95-py2.4.egg`` instead of ``django``. In this case, edit the file
541
``setuptools.pth`` and remove the line that references the Django ``.egg``
542
file. Then copy the branch's version of the ``django`` directory into
545
.. _path file: http://docs.python.org/lib/module-site.html
550
Django's release numbering works as follows:
552
* Versions are numbered in the form ``A.B`` or ``A.B.C``.
554
* ``A`` is the major version number, which is only incremented for major
555
changes to Django, and these changes are not necessarily
556
backwards-compatible. That is, code you wrote for Django 6.0 may break
557
when we release Django 7.0.
559
* ``B`` is the minor version number, which is incremented for large yet
560
backwards compatible changes. Code written for Django 6.4 will continue
561
to work under Django 6.5.
563
A minor release may deprecate certain features in previous releases. If a
564
feature in version ``A.B`` is deprecated, it will continue to work in
565
version ``A.B+1``. In version ``A.B+2``, use of the feature will raise a
566
``PendingDeprecationWarning`` but will continue to work. Version
567
``A.B+3`` will remove the feature entirely. Major point releases will
568
always remove deprecated features immediately.
570
* ``C`` is the micro version number which, is incremented for bug and
571
security fixes. A new micro-release will always be 100%
572
backwards-compatible with the previous micro-release.
574
* In some cases, we'll make release candidate releases. These are of the
575
form ``A.BrcN``, which means the ``Nth`` candidate release of version
578
An exception to this version numbering scheme is the pre-1.0 Django code.
579
There's no guarantee of backwards-compatibility until the 1.0 release.
581
In Subversion, each Django release will be tagged under `tags/releases`_. If
582
it's necessary to release a bug fix release or a security release that doesn't
583
come from the trunk, we'll copy that tag to ``branches/releases`` to make the
589
Once a feature's been requested and discussed, eventually we'll have a decision
590
about whether to include the feature or drop it.
592
Whenever possible, we strive for a rough consensus. To that end, we'll often
593
have informal votes on `django-developers`_ about a feature. In these votes we
594
follow the voting style invented by Apache and used on Python itself, where
595
votes are given as +1, +0, -0, or -1. Roughly translated, these votes mean:
597
* +1: "I love the idea and I'm strongly committed to it."
599
* +0: "Sounds OK to me."
601
* -0: "I'm not thrilled, but I won't stand in the way."
603
* -1: "I strongly disagree and would be very unhappy to see the idea turn
606
Although these votes on django-developers are informal, they'll be taken very
607
seriously. After a suitable voting period, if an obvious consensus arises
608
we'll follow the votes.
610
However, consensus is not always possible. Tough decisions will be discussed by
611
all full committers and finally decided by the Benevolent Dictators for Life,
617
Django has two types of committers:
620
These are people who have a long history of contributions to Django's
621
codebase, a solid track record of being polite and helpful on the mailing
622
lists, and a proven desire to dedicate serious time to Django's development.
624
The bar is very high for full commit access. It will only be granted by
625
unanimous approval of all existing full committers, and the decision will err
626
on the side of rejection.
629
These are people who are "domain experts." They have direct check-in access
630
to the subsystems that fall under their jurisdiction, and they're given a
631
formal vote in questions that involve their subsystems. This type of access
632
is likely to be given to someone who contributes a large subframework to
633
Django and wants to continue to maintain it.
635
Like full committers, partial commit access is by unanimous approval of all
636
full committers (and any other partial committers in the same area).
637
However, the bar is set lower; proven expertise in the area in question is
638
likely to be sufficient.
640
To request commit access, please contact an existing committer privately. Public
641
requests for commit access are potential flame-war starters, and will be ignored.
643
.. _community page: http://www.djangoproject.com/community/
644
.. _ticket tracker: http://code.djangoproject.com/newticket
645
.. _django-developers: http://groups.google.com/group/django-developers
646
.. _FAQ: http://www.djangoproject.com/documentation/faq/
647
.. _search the tracker: http://code.djangoproject.com/search
648
.. _django-users: http://groups.google.com/group/django-users
649
.. _`#django`: irc://irc.freenode.net/django
650
.. _list of tickets with patches: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority
651
.. _PEP 8: http://www.python.org/peps/pep-0008.html
652
.. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n
653
.. _`tags/releases`: http://code.djangoproject.com/browser/django/tags/releases
added
removed
docs/contributing.txt
