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.
To use a branch, you’ll need to do two things:
site-packages directory at the branch’s version of
the django package rather than the version you already have
installed.To get the latest version of a branch’s code, check it out using Subversion:
svn co https://code.djangoproject.com/svn/django/branches/<branch>/
...where <branch> is the branch’s name. See the list of branch names.
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:
svn switch https://code.djangoproject.com/svn/django/branches/<branch>/
The advantage of using svn switch instead of svn co 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 svn switch, 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:
# Trunk is a svn checkout of:
# https://code.djangoproject.com/svn/django/trunk/
#
/path/to/trunk
# <branch> is a svn checkout of:
# https://code.djangoproject.com/svn/django/branches/<branch>/
#
#/path/to/<branch>
# On windows a path may look like this:
# C:/path/to/<branch>
Sep 27, 2017