django/docs/internals/contributing/writing-code/branch-policy.txt

=============
Branch policy
=============

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:

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

    2. Feature branches using SVN have a higher bar. If you want a branch
       in SVN itself, you'll need a "mentor" among the :doc:`core committers
       </internals/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.

.. _git: http://git-scm.com/
.. _mercurial: http://mercurial.selenic.com/
.. _bazaar: http://bazaar.canonical.com/
.. _django branches: http://code.djangoproject.com/wiki/DjangoBranches

Branch rules
------------

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.

.. _svnmerge.py: http://www.orcaware.com/svn/wiki/Svnmerge.py

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.

Using branches
--------------

To use a branch, you'll need to do two things:

    * Get the branch's code through Subversion.

    * Point your Python ``site-packages`` directory at the branch's version of
      the ``django`` package rather than the version you already have
      installed.

Getting the code from Subversion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To get the latest version of a branch's code, check it out using Subversion:

.. code-block:: bash

    svn co http://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:

.. code-block:: bash

    svn switch http://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.)

.. _list of branch names: http://code.djangoproject.com/browser/django/branches

.. _pointing-python-at-the-new-django-version:

Pointing Python at the new Django version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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.4/site-packages`` or
``/usr/local/lib/python2.4/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``) which should
work on all systems (including Windows, which doesn't have symlinks
available). 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:
    #   http://code.djangoproject.com/svn/django/trunk/
    #
    /path/to/trunk

    # <branch> is a svn checkout of:
    #   http://code.djangoproject.com/svn/django/branches/<branch>/
    #
    #/path/to/<branch>

    # On windows a path may look like this:
    # C:/path/to/<branch>

If you're using Django 0.95 or earlier and installed it using
``python setup.py install``, you'll have a directory called something like
``Django-0.95-py2.4.egg`` instead of ``django``. In this case, edit the file
``setuptools.pth`` and remove the line that references the Django ``.egg``
file. Then copy the branch's version of the ``django`` directory into
``site-packages``.

.. _path file: http://docs.python.org/library/site.html
.. _django-developers: http://groups.google.com/group/django-developers