-
Notifications
You must be signed in to change notification settings - Fork 2
/
SVNtips.html
312 lines (227 loc) · 10.2 KB
/
SVNtips.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
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;
charset=iso-8859-1">
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#0000EF" vlink="#51188E" alink="#FF0000">
<h1>Subversion Techniques</h1>
<p><i>This info is for reference to the core developers. Use of anonymous
Subversion for outsiders is not explicitly covered here, but for now and as long as the
load on the server remains manageable, will be identical, with the exception
that only core developers can commit changes.
<p> We assume that Subversion is installed and basic Subversion techniques are
understood; for background information, <a href= "http://svnbook.red-bean.com/"><i
>Version Control with Subversion</i></a> provides an excellent reference. One of
its authors has also put together <a href=
"http://www.onlamp.com/pub/a/onlamp/2004/08/19/subversiontips.html">The Top
Ten Subversion Tips for CVS Users</a> which is very helpful.</i>
<h3>Preliminaries</h3>
<p> There are two main development branches for R. For reference, we call them
<tt>r-devel</tt>, and
<tt>r-release-branch</tt>.
<p> From the beginning of the release process for R-x.y.0 the two versions
work towards
<pre><kbd>
Version Name Branch URL (after https://svn.r-project.org/)
-----------------------------------------------------------------------------------
R-x.(y+1).0 r-devel [none] R/trunk/
R-x.y.z r-release-branch R-x-y-branch R/branches/R-x-y-branch/
</kbd></pre>
Note that <em>R-patched</em> is also used for the <em>current</em> r-release-branch.
The "Branch" column refers to the Subversion branch name. The logic is
that all releases (R-x.y.z, z>=0) are made from the branch named
"R-x-y-branch".
<p> NB: With Subversion we will develop as follows:
<ol>
<li>Where possible, develop <b>all</b> changes on the trunk, even
bug fixes, and commit them there first. </li>
<li>When a change meets the <a href="devel-guidelines.txt">development guidelines</a>
for inclusion in r-patched, port it from the trunk to the branch.
</ol></p>
<p> In what follows, I use the reference names also as directory
names. All developers are encouraged to use the same names, to provide
us with a common reference.
<h3><a name="CO-devel">Checking out a development branch</a></h3>
<p> (By a development branch, I mean either the trunk or the release
branch.)
<p>
I shall
assume the <tt>bash</tt> shell in the following, for simplicity, and
create the three development directories under $RTOP.
<pre><kbd>
export REPOS=https://svn.r-project.org/R
export RTOP=~ #adjust as necessary
</kbd></pre>
<h4>The trunk revision</h4>
(aka "r-devel")
<pre><kbd>
cd $RTOP
svn co $REPOS/trunk r-devel/R
</kbd></pre>
<p>
The checked out
directory will be called "$RTOP/r-devel/R". Change the
"r-devel/R" argument to call it something else.
<h4> Current release branch</h4>
(aka "r-release-branch")
<pre><kbd>
cd $RTOP
svn co $REPOS/branches/R-2-4-branch r-release-branch/R
</kbd></pre>
<h3><a name="CO-rel">Checking out a specific release version</a></h3>
Release versions are labeled with a tag of the form R-1-2-3. (For
obscure reasons, non-patch versions up to R-1.3.0 were labeled R-1-3
and not R-1-3-0. This was changed starting with R-1.4.0.). You can
check out an old version simply with
<p>
<tt>svn co $REPOS/R/tags/R-1-2-3 R</tt>
<p>Notice that release versions are under the tags directory, not the
branches directory. You should not change
a released version and commit the changes back, but unlike CVS, Subversion
will not prevent you from doing this. If you do it accidentally, please
<a href="http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.branchmerge.commonuses.undo">
undo your change</a> immediately.
<h3><a name="updating">Updating</a></h3>
To update a source tree with the latest changes, just go to the
relevant top-level directory (e.g. $RTOP/r-devel/R) and say
<p>
<tt>svn up </tt>
<p>If you have uncommitted changes that conflict with other updates, you will need
to fix the conflicts and call <tt>svn resolved</tt> to tell Subversion that they are fixed
before you'll be able to commit that file.
<p>If you want to make completely sure that the files come from a
given branch, use <tt> svn switch https://svn.r-project.org/R/branches/somebranch</tt>.
<p>If you are on a slow connection, you can also use the <tt>switch</tt>
command instead of doing a new checkout, e.g.
<p>
<tt>svn switch $REPOS/R/branches/R-2-4-branch</tt>
<p>To switch to the trunk revision from a branch revision, use
<p>
<tt>svn switch $REPOS/R/trunk</tt>
<p> I do not know if Subversion is capable of getting things wrong,
e.g. if interrupted in the middle of an update.
<h3>Committing</h3>
To put your modified versions back in the repository, just say
<tt>svn commit -m'describe change' FILE1 FILE2 ...</tt>
<p>or just
<p>
<tt>svn commit</tt>
<p>in which case all changes in the current working directory will
be committed, and you'll be asked for a change comment.
<p>Notice that commits work on the trunk, branch
and tag revisions, but they should never be made on the tags.
Tags represent the status of the files at a
given time in the past and should not be changed.
<h3><a name="port-from-trunk"> Porting patches from r-devel to r-release-branch</a> </h3>
<p>Almost all changes should be made on the r-devel trunk first. After testing and
committing them there, bug fixes and <a href="devel-guidelines.txt">some other
minor changes</a> should be ported to the <em>r-patched</em> branch
aka <em>r-release-branch</em> .
Make note of the revision number of your commit to the trunk. For example,
<pre><kbd>
$ svn commit -m'Sample commit'
Adding tests\added.file
Sending tests\minitab.R
Transmitting file data ..
Committed revision 140.
</kbd></pre>
was revision 140. The changeset you want is <tt>-r 139:140</tt>,
i.e. the changes between <tt>r139</tt> and <tt>r140</tt>. However,
for a simple changeset we can use a simpler notation, <tt>-c 140</tt>.
(This requires <tt>svn >= 1.4.0</tt>.)
<p>Change to the r-release-branch directory, merge your changes, check and
fix any conflicts, and commit.
<pre><kbd>
export REPOS=https://svn.r-project.org/R
export RTOP=~ #adjust as necessary
cd $RTOP/r-release-branch/R
svn merge -c 140 $REPOS/trunk
svn status # Look for C, indicating a conflict
# fix conflicts... (remember to use svn resolved for each)
svn commit -m 'ported r140 (sample changes to tests) from trunk'
</kbd></pre>
<h4><a name=reverting> Backing out aka 'Reverting'</a></h4>
To back out (aka 'revert') a simple changeset, use <tt>merge</tt> with
a <em>negated</em> number, e.g.
<pre><kbd>
svn merge -c -140 $REPOS/...
</kbd></pre>
</p>
<h3> Updating from r-patched to r-devel, specific changes</h3>
If revisions are made on the r-patched branch that should have been made to
r-devel, then just follow the same procedure as above, but merge the changes
in the opposite direction. Assuming r140 was made to the branch
instead of the trunk:
<pre><kbd>
export REPOS=https://svn.r-project.org/R
export RTOP=~/R-devel #adjust as necessary
export TAG=R-2-4-branch
cd $RTOP/r-devel/R
svn merge -c 140 $REPOS/branches/$TAG
svn status # Look for C, indicating a conflict
# fix conflicts... (remember to use 'svn resolved ..' for each)
svn commit -m 'merged r-patched change r140 into the trunk'
</kbd></pre>
<h3> Updating from r-patched to r-devel, entire tree</h3>
This procedure should never be necessary, and is not safe, in that
the last-patch-update tag is not normally maintained.
<h3><a name="experi-branches"> Handling experimental branches</a></h3>
<!-- --------------- -->
Suppose you want to have a branch to hold your volatile changes, let's
say R-Tk. We'll keep a file recording when we did merges from the trunk,
but the information is all available in the log if this file gets lost.
<!-- FIXME: nicer formatting (but rather __after__ moving to markdown -->
<pre><kbd>
(A) Creating the branch (keeping a "log-file" to be re-used)
===================
export REPOS=https://svn.r-project.org/R
mkdir r-experimental
cd r-experimental
svn cp -m'Create R-tk' $REPOS/trunk $REPOS/branches/R-Tk > R-Tk-updates
cat R-Tk-updates # Keeps a record of revision numbers when your branch was last in sync with the trunk
svn checkout $REPOS/branches/R-Tk R
(B) Hacking on the branch
=====================
Just like on the release branch:
svn update
#..hack, hack, hack....
svn commit -m'hacked blah'
(C) Updating from r-devel (aka "main trunk")
========================================
# Use log-file'to find when we did our last merge, e.g. r141 :
tail -1 R-Tk-updates
svn log -r HEAD $REPOS # Find the HEAD revision, e.g. r143
svn merge -r 141:143 $REPOS/trunk
# resolve conflicts if any
svn commit -m 'ported r141:143 from main'
# Update log-file, saving the revision number, for the next merge:
echo merged to r143 >> R-Tk-updates
(D) Merging the hack back into r-devel
==================================
# Look up the revision number when we created the branch, e.g. r141 :
head R-Tk-updates
cd ~/r-devel/R
svn info # find the current revision number of the repository, e.g. r143
svn merge -r 141:143 $REPOS/branches/R-Tk # resolve conflicts if any
svn commit -m'merged Tk branch r141:143 into trunk'
(E) All done, so clean up
==================================
svn delete -m'Deleting R-Tk' $REPOS/branches/R-Tk
(F) Oops, more work to do on R-Tk: resurrect it
==================================
svn log -v $REPOS/branches | grep -B 2 R-Tk # look up when it was deleted (in r144)
svn copy -m'Resurrecting R-Tk branch' -r 143 $REPOS/branches/R-Tk $REPOS/branches/R-Tk
</kbd></pre>
<h2><a name="release"> Release procedures </a></h2>
<!-- ------- ================== -->
This is now handled almost automatically by various scripts, which can
be found on the <a href="https://svn.r-project.org/R-dev-web/trunk/">
developer page</a>, typically via <tt>svn</tt>/subversion, rather than web browser.
Briefly, there are two build scripts, one for pre-releases and one for
the final build. The former are run every morning during the run-in
period by a cron job. Two auxiliary scripts set up the new relelase
branch (needed for x.y.0 releases) and the intermediate version
changes.
</body>
</html>