www/branching.html

   1 <html>
   2 <head>
   3 <title>SCons Branching and Merging</title>
   4 </head>
   5 <body>
   6
   7 <div id="apphead">
   8 <h1><small>scons</small><br />SCons Branching and Merging</h1>
   9 </div>
  10
  11 <p>
  12 This page covers how we handle branching and merging
  13 in the SCons development tree.
  14 We'll use
  15 <a href="http://www.dellroad.org/svnmerge/index">svnmerge</a>
  16 to keep track of what changes haven't been merged in each direction.
  17 Some of the concepts and steps below have been
  18 swiped from a pretty decent
  19 <a href="http://kenkinder.com/svnmerge/">svnmerge howto</a>
  20 created by Ken Kinder,
  21 with liberal help from our Gary Oberbrunner.
  22 </p>
  23
  24 <div class="h2 app" style="border-left: 0px" id="branches">
  25
  26 <h2>Branches</h2>
  27
  28 <p>
  29 These are the SCons development branches and their intended uses.
  30 </p>
  31
  32 <ul>
  33
  34 <li>
  35 <strong><tt>trunk</tt></strong>
  36 <p>
  37 The main code line from which SCons gets released.
  38 This currently lags patches that the mailing list
  39 discussions describe as "checked in to Subversion."
  40 The real latest-and-greatest checked-in source
  41 containing SK's patches is in
  42 <tt>branches/core</tt>.
  43 This is, however, where we check in
  44 web site changes into the
  45 <tt>www/</tt> and <tt>scons.org/</tt> subdirectories
  46 (for the <a href="http://scons.tigris.org/">tigris.org</a>
  47 and <a href="http://www.scons.org/">scons.org</a>
  48 web sites, respectively).
  49 </p>
  50 </li>
  51
  52 <li>
  53 <strong><tt>branches/core</tt></strong>
  54 <p>
  55 The main development branch for changes to
  56 the SCons infrastructure.
  57 This is where SK checks in most of the
  58 stuff he's working on
  59 and which gets sent for review to the
  60 scons-dev mailing list.
  61 This branch's parent is <tt>trunk</tt>.
  62 </p>
  63 </li>
  64
  65 <li>
  66 <strong><tt>branches/packaging</tt></strong>
  67 <p>
  68 Development branch for the packaging work
  69 that Philipp Scholl is working on
  70 as a Google Summer of Code project.
  71 </p>
  72 </li>
  73
  74 <li>
  75 <strong><tt>branches/sigrefactor</tt></strong>
  76 <p>
  77 Development branch for the Big Signature Refactoring
  78 that SK has been working on since the last ice age.
  79 This branch's parent is <tt>branches/core</tt>.
  80 </p>
  81 </li>
  82
  83 <li>
  84 <strong><tt>branches/testing</tt></strong>
  85 <p>
  86 A branch for work on the SCons testing infrastructure.
  87 This branch's parent is <tt>branches/core</tt>.
  88 Not very active at the moment,
  89 because most of that work is just going in right in
  90 <tt>branches/core</tt>.
  91 </p>
  92 </li>
  93
  94 <li>
  95 <strong><tt>branches/tools</tt></strong>
  96 <p>
  97 The branch intended for people to check in new features to Tool modules.
  98 If you want to contribute a change here,
  99 go see the
 100 <a href="tools-changes.html">step-by-step instructions</a>
 101 for doing so.
 102 This branch's parent is <tt>trunk</tt>.
 103 </p>
 104 </li>
 105
 106 </ul>
 107
 108 <p>
 109 </p>
 110
 111 <h2>How to create a branch off the trunk and initialize it for bi-directional merging</h2>
 112
 113 <p>
 114 This should take place between any branch and its parent
 115 to set up to <tt>svnmerge</tt> to handle the
 116 tracking as we go forward.
 117 </p>
 118
 119 <pre>
 120 $ export SVN=http://scons.tigris.org/svn/scons
 121 $ cd my_working_directory/trunk
 122 $ svn cp $SVN/trunk $SVN/branches/new_branch
 123 $ svn commit
 124 $ cd ..
 125 $ svn co $SVN/branches/new_branch
 126 $ cd new_branch
 127 $ svnmerge init -f commit.txt $SVN/trunk
 128 $ cd ../../trunk
 129 $ svnmerge init -f commit.txt $SVN/branches/new_branch
 130 $ svn commit -F commit.txt && rm commit.txt
 131 $ cd ../branches/new_branch
 132 $ svn commit -F commit.txt && rm commit.txt
 133 </pre>
 134
 135 <p>
 136 You can actually do both the <tt>svnmerge init</tt>
 137 and <tt>svn commit</tt> on one branch (in one directory)
 138 and then do both on the other branch,
 139 but doing it this way makes both of them end up with
 140 the same revision number in the <tt>svnmerge</tt> property,
 141 which is nice and symmetric.
 142 </p>
 143
 144 <h2>How to merge changes from the trunk to a development branch</h2>
 145
 146 <p>
 147 This brings a branch in sync with the latest changes that
 148 have made it into the trunk for release
 149 (usually by being promoted from other branches,
 150 we typically don't do work directly on the trunk).
 151 </p>
 152
 153 <pre>
 154 $ export SVN=http://scons.tigris.org/svn/scons
 155 $ cd my_working_directory/new_branch
 156 $ svn up
 157 $ svnmerge avail -b -S $SVN/trunk -l
 158 $ svnmerge merge -b -S $SVN/trunk -f commit.txt
 159 $ svn resolved .
 160 $ svn diff
 161 $ python runtest.py -a
 162 $ svn commit -F commit.txt && rm commit.txt
 163 </pre>
 164
 165 <p>
 166 The <tt>svn resolved .</tt> is there because there may be a
 167 conflict on the <tt>svnmerge-integrated</tt>property
 168 that's attached to the directory to track what changes
 169 have or have not already been merged from the trunk.
 170 </p>
 171
 172 <h2>How to merge changes from a development branch to the trunk</h2>
 173
 174 <p>
 175 This promotes the branch changes into the trunk.
 176 Note that you should <emphasis>really</emphasis>
 177 first make sure that your branch has already
 178 merged any changes from the trunk
 179 (see previous section) before doing this,
 180 or else you're likely to overwrite any work
 181 that's already been submitted up.
 182 </p>
 183
 184 <pre>
 185 $ export SVN=http://scons.tigris.org/svn/scons
 186 $ cd my_working_directory/trunk
 187 $ svn up
 188 $ svnmerge avail -b -S $SVN/branches/new_branch -l
 189 $ svnmerge merge -b -S $SVN/branches/new_branch -f commit.txt
 190 $ svn resolved .
 191 $ svn diff
 192 $ python runtest.py -a
 193 $ svn commit -F commit.txt && rm commit.txt
 194 </pre>
 195
 196 <p>
 197 The <tt>svn resolved .</tt> is there because there may be a
 198 conflict on the <tt>svnmerge-integrated</tt>property
 199 that's attached to the directory to track what changes
 200 have or have not already been merged from the development branch.
 201 </p>
 202
 203 </div>
 204
 205 </body>
 206 </html>