www/branching.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206

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