In general, the trunk must be kept stable. People should be able to run
production sites against the trunk at any time. Additionally, commits to trunk
ought to be as atomic as possible – smaller changes are better. Thus, large
feature changes – that is, changes too large to be encapsulated in a single
patch, or changes that need multiple eyes on them – must happen on dedicated
branches.

This means that if you want to work on a large feature – anything that would
take more than a single patch, or requires large-scale refactoring – you need
to do it on a feature branch. Our development process recognizes two options
for feature branches:

Feature branches using a distributed revision control system like
Git, Mercurial, Bazaar, etc.

If you’re familiar with one of these tools, this is probably your best
option since it doesn’t require any support or buy-in from the Django
core developers.

However, do keep in mind that Django will continue to use Subversion
for the foreseeable future, and this will naturally limit the
recognition of your branch. Further, if your branch becomes eligible
for merging to trunk you’ll need to find a core developer familiar
with your DVCS of choice who’ll actually perform the merge.

If you do decided to start a distributed branch of Django and choose to
make it public, please add the branch to the Django branches wiki
page.

Feature branches using SVN have a higher bar. If you want a branch
in SVN itself, you’ll need a “mentor” among the core committers. This person is responsible for actually
creating the branch, monitoring your process (see below), and
ultimately merging the branch into trunk.

If you want a feature branch in SVN, you’ll need to ask in
django-developers for a mentor.

We’ve got a few rules for branches born out of experience with what makes a
successful Django branch.

DVCS branches are obviously not under central control, so we have no way of
enforcing these rules. However, if you’re using a DVCS, following these rules
will give you the best chance of having a successful branch (read: merged back
to trunk).

Developers with branches in SVN, however, must follow these rules. The
branch mentor will keep on eye on the branch and will delete it if these
rules are broken.

Only branch entire copies of the Django tree, even if work is only
happening on part of that tree. This makes it painless to switch to a
branch.

Merge changes from trunk no less than once a week, and preferably every
couple-three days.

In our experience, doing regular trunk merges is often the difference
between a successful branch and one that fizzles and dies.

If you’re working on an SVN branch, you should be using svnmerge.py
to track merges from trunk.

Keep tests passing and documentation up-to-date. As with patches,
we’ll only merge a branch that comes with tests and documentation.

Once the branch is stable and ready to be merged into the trunk, alert
django-developers.

After a branch has been merged, it should be considered “dead”; write access
to it will be disabled, and old branches will be periodically “trimmed.”
To keep our SVN wrangling to a minimum, we won’t be merging from a given
branch into the trunk more than once.

Alternatively, you can automatically convert an existing directory of the
Django source code as long as you’ve checked it out via Subversion. To do the
conversion, execute this command from within your django directory:

The advantage of using svnswitch instead of svnco is that the
switch command retains any changes you might have made to your local copy
of the code. It attempts to merge those changes into the “switched” code. The
disadvantage is that it may cause conflicts with your local changes if the
“switched” code has altered the same lines of code.

(Note that if you use svnswitch, you don’t need to point Python at the
new version, as explained in the next section.)

Once you’ve retrieved the branch’s code, you’ll need to change your Python
site-packages directory so that it points to the branch version of the
django directory. (The site-packages directory is somewhere such as
/usr/lib/python2.7/site-packages or
/usr/local/lib/python2.7/site-packages or C:\Python\site-packages.)

The simplest way to do this is by renaming the old django directory to
django.OLD and moving the trunk version of the code into the directory
and calling it django.

Alternatively, you can use a symlink called django that points to the
location of the branch’s django package. If you want to switch back, just
change the symlink to point to the old code.

A third option is to use a path file (<something>.pth). This is a feature of
the site module. First, make sure there are no files, directories or
symlinks named django in your site-packages directory. Then create a
text file named django.pth and save it to your site-packages directory.
That file should contain a path to your copy of Django on a single line and
optional comments. Here is an example that points to multiple branches. Just
uncomment the line for the branch you want to use (‘trunk’ in this example) and
make sure all other lines are commented: