172 lines
7.0 KiB
Plaintext
172 lines
7.0 KiB
Plaintext
=============
|
|
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.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 :mod:`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:
|
|
# 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>
|
|
|
|
.. _django-developers: http://groups.google.com/group/django-developers
|