lib/django-1.4/docs/internals/contributing/writing-code/branch-policy.txt - external/googleappengine/python - Git at Google

 =============
 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: https://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 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:

 .. code-block:: bash

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

 .. _list of branch names: https://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:
     #   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>

 .. _django-developers: http://groups.google.com/group/django-developers
	=============
	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: https://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 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:

	.. code-block:: bash

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

	.. _list of branch names: https://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:
	# 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>

	.. _django-developers: http://groups.google.com/group/django-developers