scons_eyan / www / branching.html

<html>
<head>
<title>SCons Branching and Merging</title>
</head>
<body>

<div id="apphead">
<h1><small>scons</small><br />SCons Branching and Merging</h1>
</div>

<p>
This page covers how we handle branching and merging
in the SCons development tree.
We'll use
<a href="http://www.dellroad.org/svnmerge/index">svnmerge</a>
to keep track of what changes haven't been merged in each direction.
Some of the concepts and steps below have been
swiped from a pretty decent
<a href="http://kenkinder.com/svnmerge/">svnmerge howto</a>
created by Ken Kinder,
with liberal help from our Gary Oberbrunner.
</p>

<div class="h2 app" style="border-left: 0px" id="branches">

<h2>Branches</h2>

<p>
These are the SCons development branches and their intended uses.
</p>

<ul>

<li>
<strong><tt>trunk</tt></strong>
<p>
The main code line from which SCons gets released.
This currently lags patches that the mailing list
discussions describe as "checked in to Subversion."
The real latest-and-greatest checked-in source
containing SK's patches is in
<tt>branches/core</tt>.
This is, however, where we check in
web site changes into the
<tt>www/</tt> and <tt>scons.org/</tt> subdirectories
(for the <a href="http://scons.tigris.org/">tigris.org</a>
and <a href="http://www.scons.org/">scons.org</a>
web sites, respectively).
</p>
</li>

<li>
<strong><tt>branches/core</tt></strong>
<p>
The main development branch for changes to
the SCons infrastructure.
This is where SK checks in most of the
stuff he's working on
and which gets sent for review to the
scons-dev mailing list.
This branch's parent is <tt>trunk</tt>.
</p>
</li>

<li>
<strong><tt>branches/packaging</tt></strong>
<p>
Development branch for the packaging work
that Philipp Scholl is working on
as a Google Summer of Code project.
</p>
</li>

<li>
<strong><tt>branches/sigrefactor</tt></strong>
<p>
Development branch for the Big Signature Refactoring
that SK has been working on since the last ice age.
This branch's parent is <tt>branches/core</tt>.
</p>
</li>

<li>
<strong><tt>branches/testing</tt></strong>
<p>
A branch for work on the SCons testing infrastructure.
This branch's parent is <tt>branches/core</tt>.
Not very active at the moment,
because most of that work is just going in right in
<tt>branches/core</tt>.
</p>
</li>

<li>
<strong><tt>branches/tools</tt></strong>
<p>
The branch intended for people to check in new features to Tool modules.
If you want to contribute a change here,
go see the
<a href="tools-changes.html">step-by-step instructions</a>
for doing so.
This branch's parent is <tt>trunk</tt>.
</p>
</li>

</ul>

<p>
</p>

<h2>How to create a branch off the trunk and initialize it for bi-directional merging</h2>

<p>
This should take place between any branch and its parent
to set up to <tt>svnmerge</tt> to handle the
tracking as we go forward.
</p>

<pre>
$ export SVN=http://scons.tigris.org/svn/scons
$ cd my_working_directory/trunk
$ svn cp $SVN/trunk $SVN/branches/new_branch
$ svn commit
$ cd ..
$ svn co $SVN/branches/new_branch
$ cd new_branch
$ svnmerge init -f commit.txt $SVN/trunk
$ cd ../../trunk
$ svnmerge init -f commit.txt $SVN/branches/new_branch
$ svn commit -F commit.txt && rm commit.txt
$ cd ../branches/new_branch
$ svn commit -F commit.txt && rm commit.txt
</pre>

<p>
You can actually do both the <tt>svnmerge init</tt>
and <tt>svn commit</tt> on one branch (in one directory)
and then do both on the other branch,
but doing it this way makes both of them end up with
the same revision number in the <tt>svnmerge</tt> property,
which is nice and symmetric.
</p>

<h2>How to merge changes from the trunk to a development branch</h2>

<p>
This brings a branch in sync with the latest changes that
have made it into the trunk for release
(usually by being promoted from other branches,
we typically don't do work directly on the trunk).
</p>

<pre>
$ export SVN=http://scons.tigris.org/svn/scons
$ cd my_working_directory/new_branch
$ svn up
$ svnmerge avail -b -S $SVN/trunk -l
$ svnmerge merge -b -S $SVN/trunk -f commit.txt
$ svn resolved .
$ svn diff
$ python runtest.py -a
$ svn commit -F commit.txt && rm commit.txt
</pre>

<p>
The <tt>svn resolved .</tt> is there because there may be a
conflict on the <tt>svnmerge-integrated</tt>property
that's attached to the directory to track what changes
have or have not already been merged from the trunk.
</p>

<h2>How to merge changes from a development branch to the trunk</h2>

<p>
This promotes the branch changes into the trunk.
Note that you should <emphasis>really</emphasis>
first make sure that your branch has already
merged any changes from the trunk
(see previous section) before doing this,
or else you're likely to overwrite any work
that's already been submitted up.
</p>

<pre>
$ export SVN=http://scons.tigris.org/svn/scons
$ cd my_working_directory/trunk
$ svn up
$ svnmerge avail -b -S $SVN/branches/new_branch -l
$ svnmerge merge -b -S $SVN/branches/new_branch -f commit.txt
$ svn resolved .
$ svn diff
$ python runtest.py -a
$ svn commit -F commit.txt && rm commit.txt
</pre>

<p>
The <tt>svn resolved .</tt> is there because there may be a
conflict on the <tt>svnmerge-integrated</tt>property
that's attached to the directory to track what changes
have or have not already been merged from the development branch.
</p>

</div>

</body>
</html>
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.