<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Branch policy — Django 1.4.5 documentation</title>
<link rel="stylesheet" href="../../../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../../',
VERSION: '1.4.5',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../../../_static/jquery.js"></script>
<script type="text/javascript" src="../../../_static/underscore.js"></script>
<script type="text/javascript" src="../../../_static/doctools.js"></script>
<link rel="top" title="Django 1.4.5 documentation" href="../../../index.html" />
<link rel="up" title="Writing code" href="index.html" />
<link rel="next" title="Writing documentation" href="../writing-documentation.html" />
<link rel="prev" title="Submitting patches" href="submitting-patches.html" />
<script type="text/javascript" src="../../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../../../ref/templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../../index.html">Django 1.4.5 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../../../index.html">Home</a> |
<a title="Table of contents" href="../../../contents.html">Table of contents</a> |
<a title="Global index" href="../../../genindex.html">Index</a> |
<a title="Module index" href="../../../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="submitting-patches.html" title="Submitting patches">previous</a>
|
<a href="../../index.html" title="Django internals" accesskey="U">up</a>
|
<a href="../writing-documentation.html" title="Writing documentation">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="internals-contributing-writing-code-branch-policy">
<div class="section" id="s-branch-policy">
<span id="branch-policy"></span><h1>Branch policy<a class="headerlink" href="#branch-policy" title="Permalink to this headline">¶</a></h1>
<p>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.</p>
<p>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:</p>
<ol class="arabic">
<li><p class="first">Feature branches using a distributed revision control system like
<a class="reference external" href="http://git-scm.com/">Git</a>, <a class="reference external" href="http://mercurial.selenic.com/">Mercurial</a>, <a class="reference external" href="http://bazaar.canonical.com/">Bazaar</a>, etc.</p>
<p>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.</p>
<p>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.</p>
<p>If you do decided to start a distributed branch of Django and choose to
make it public, please add the branch to the <a class="reference external" href="https://code.djangoproject.com/wiki/DjangoBranches">Django branches</a> wiki
page.</p>
</li>
<li><p class="first">Feature branches using SVN have a higher bar. If you want a branch
in SVN itself, you’ll need a “mentor” among the <a class="reference internal" href="../../committers.html"><em>core committers</em></a>. This person is responsible for actually
creating the branch, monitoring your process (see below), and
ultimately merging the branch into trunk.</p>
<p>If you want a feature branch in SVN, you’ll need to ask in
<a class="reference external" href="http://groups.google.com/group/django-developers">django-developers</a> for a mentor.</p>
</li>
</ol>
<div class="section" id="s-branch-rules">
<span id="branch-rules"></span><h2>Branch rules<a class="headerlink" href="#branch-rules" title="Permalink to this headline">¶</a></h2>
<p>We’ve got a few rules for branches born out of experience with what makes a
successful Django branch.</p>
<p>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).</p>
<p>Developers with branches in SVN, however, <strong>must</strong> follow these rules. The
branch mentor will keep on eye on the branch and <strong>will delete it</strong> if these
rules are broken.</p>
<ul>
<li><p class="first">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.</p>
</li>
<li><p class="first">Merge changes from trunk no less than once a week, and preferably every
couple-three days.</p>
<p>In our experience, doing regular trunk merges is often the difference
between a successful branch and one that fizzles and dies.</p>
<p>If you’re working on an SVN branch, you should be using <a class="reference external" href="http://www.orcaware.com/svn/wiki/Svnmerge.py">svnmerge.py</a>
to track merges from trunk.</p>
</li>
<li><p class="first">Keep tests passing and documentation up-to-date. As with patches,
we’ll only merge a branch that comes with tests and documentation.</p>
</li>
</ul>
<p>Once the branch is stable and ready to be merged into the trunk, alert
<a class="reference external" href="http://groups.google.com/group/django-developers">django-developers</a>.</p>
<p>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.</p>
</div>
<div class="section" id="s-using-branches">
<span id="using-branches"></span><h2>Using branches<a class="headerlink" href="#using-branches" title="Permalink to this headline">¶</a></h2>
<p>To use a branch, you’ll need to do two things:</p>
<ul class="simple">
<li>Get the branch’s code through Subversion.</li>
<li>Point your Python <tt class="docutils literal"><span class="pre">site-packages</span></tt> directory at the branch’s version of
the <tt class="docutils literal"><span class="pre">django</span></tt> package rather than the version you already have
installed.</li>
</ul>
<div class="section" id="s-getting-the-code-from-subversion">
<span id="getting-the-code-from-subversion"></span><h3>Getting the code from Subversion<a class="headerlink" href="#getting-the-code-from-subversion" title="Permalink to this headline">¶</a></h3>
<p>To get the latest version of a branch’s code, check it out using Subversion:</p>
<div class="highlight-bash"><div class="highlight"><pre>svn co https://code.djangoproject.com/svn/django/branches/<branch>/
</pre></div>
</div>
<p>...where <tt class="docutils literal"><span class="pre"><branch></span></tt> is the branch’s name. See the <a class="reference external" href="https://code.djangoproject.com/browser/django/branches">list of branch names</a>.</p>
<p>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 <tt class="docutils literal"><span class="pre">django</span></tt> directory:</p>
<div class="highlight-bash"><div class="highlight"><pre>svn switch https://code.djangoproject.com/svn/django/branches/<branch>/
</pre></div>
</div>
<p>The advantage of using <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">switch</span></tt> instead of <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span></tt> is that the
<tt class="docutils literal"><span class="pre">switch</span></tt> 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.</p>
<p>(Note that if you use <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">switch</span></tt>, you don’t need to point Python at the
new version, as explained in the next section.)</p>
</div>
<div class="section" id="s-pointing-python-at-the-new-django-version">
<span id="s-id1"></span><span id="pointing-python-at-the-new-django-version"></span><span id="id1"></span><h3>Pointing Python at the new Django version<a class="headerlink" href="#pointing-python-at-the-new-django-version" title="Permalink to this headline">¶</a></h3>
<p>Once you’ve retrieved the branch’s code, you’ll need to change your Python
<tt class="docutils literal"><span class="pre">site-packages</span></tt> directory so that it points to the branch version of the
<tt class="docutils literal"><span class="pre">django</span></tt> directory. (The <tt class="docutils literal"><span class="pre">site-packages</span></tt> directory is somewhere such as
<tt class="docutils literal"><span class="pre">/usr/lib/python2.7/site-packages</span></tt> or
<tt class="docutils literal"><span class="pre">/usr/local/lib/python2.7/site-packages</span></tt> or <tt class="docutils literal"><span class="pre">C:\Python\site-packages</span></tt>.)</p>
<p>The simplest way to do this is by renaming the old <tt class="docutils literal"><span class="pre">django</span></tt> directory to
<tt class="docutils literal"><span class="pre">django.OLD</span></tt> and moving the trunk version of the code into the directory
and calling it <tt class="docutils literal"><span class="pre">django</span></tt>.</p>
<p>Alternatively, you can use a symlink called <tt class="docutils literal"><span class="pre">django</span></tt> that points to the
location of the branch’s <tt class="docutils literal"><span class="pre">django</span></tt> package. If you want to switch back, just
change the symlink to point to the old code.</p>
<p>A third option is to use a path file (<tt class="docutils literal"><span class="pre"><something>.pth</span></tt>). This is a feature of
the <tt class="xref py py-mod docutils literal"><span class="pre">site</span></tt> module. First, make sure there are no files, directories or
symlinks named <tt class="docutils literal"><span class="pre">django</span></tt> in your <tt class="docutils literal"><span class="pre">site-packages</span></tt> directory. Then create a
text file named <tt class="docutils literal"><span class="pre">django.pth</span></tt> and save it to your <tt class="docutils literal"><span class="pre">site-packages</span></tt> 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:</p>
<div class="highlight-python"><pre># 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></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../../../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Branch policy</a><ul>
<li><a class="reference internal" href="#branch-rules">Branch rules</a></li>
<li><a class="reference internal" href="#using-branches">Using branches</a><ul>
<li><a class="reference internal" href="#getting-the-code-from-subversion">Getting the code from Subversion</a></li>
<li><a class="reference internal" href="#pointing-python-at-the-new-django-version">Pointing Python at the new Django version</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="submitting-patches.html">Submitting patches</a></li>
<li>Next: <a href="../writing-documentation.html">Writing documentation</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../../../index.html">Django 1.4.5 documentation</a>
<ul><li><a href="../../index.html">Django internals</a>
<ul><li><a href="../index.html">Contributing to Django</a>
<ul><li><a href="index.html">Writing code</a>
<ul><li>Branch policy</li></ul>
</li></ul></li></ul></li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../../_sources/internals/contributing/writing-code/branch-policy.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Feb 21, 2013</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="submitting-patches.html" title="Submitting patches">previous</a>
|
<a href="../../index.html" title="Django internals" accesskey="U">up</a>
|
<a href="../writing-documentation.html" title="Writing documentation">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
