1 | | [[PageOutline(1-3,Contents,inline)]] |
2 | | |
3 | | = Publishing a release = |
4 | | |
5 | | These instructions cover how to release minor and patch releases in a |
6 | | project that uses trac/subversion for revision control and project |
7 | | management. How to release major releases is not covered yet since we |
8 | | have not done that (with the exception of the first release). Release |
9 | | numbering follows the normal convention of major.minor.patch and the |
10 | | APR (see http://apr.apache.org/versioning.html) guidelines for |
11 | | releases are used. |
12 | | |
13 | | The main development is performed in the trunk branch of the |
14 | | repository. A new release branch is created for each minor release |
15 | | from the trunk and patch releases are snapshots of the minor release |
16 | | branch. This implies that patch work is performed in the minor release |
17 | | branch, and changes made release branch is transferred to the trunk |
18 | | every time a new patch release is made. Remember, patch work should be |
19 | | limited to bug fixes and important fixes only leaving development of |
20 | | new features and designs to the trunk branch. |
21 | | |
22 | | Releases should only be performed by an appointed member of the team, |
23 | | the Release Manager, and merges should be performed by a Merge |
24 | | Manager. Of course, one team member can be both managers, thus |
25 | | becoming the Release and Merge Manager. |
26 | | |
27 | | |
28 | | == Minor release procedure == |
29 | | |
30 | | This section describes what to do when publishing a minor release. |
31 | | |
32 | | === Creating a release branch === |
33 | | |
34 | | Once people agree that a new release branch should be made, the |
35 | | Release Manager creates it with the following procedure (substitute |
36 | | A.B with the version you are preparing): |
37 | | |
38 | | 1. Mark the new minor series in `NEWS` |
39 | | {{{ |
40 | | See the end for copyrights and conditions. |
41 | | |
42 | | +svndigest A.B.x series from |
43 | | + http://dev.thep/lu.se/svndigest/svn/branches/A.B-stable |
44 | | + |
45 | | Version A.B (released NOT YET) |
46 | | }}} |
47 | | commit the changes with `svn ci -m "preparing branch A.B-stable"`[[br]][[br]] |
48 | | 1. Update copyright statements with commands |
49 | | {{{ |
50 | | make check && ./bin/svncopyright -v |
51 | | }}} |
52 | | Examine the updates and commit changes with `svn ci -m "updating |
53 | | copyright statements"`[[br]][[br]] |
54 | | 1. Create a new minor branch using a one liner like |
55 | | {{{ |
56 | | svn copy ^/trunk ^/branches/A.B-stable -m "New minor version A.B branch" |
57 | | }}} |
58 | | 1. Check out a wc of the new branch |
59 | | {{{ |
60 | | svn co http://dev.thep.lu.se/svndigest/svn/branches/A.B-stable /path/to/svndigest-A.B.x |
61 | | }}} |
62 | | 1. Copy the cache from wc of trunk to wc of new branch. Due to #463 be sure to use |
63 | | version 0.9pre or newer: |
64 | | {{{ |
65 | | /path/to/svndigest-trunk/bin/svndigest-copy-cache -v -r /path/to/svndigest-trunk -t /path/to/svndigest-A.B.x |
66 | | }}} |
67 | | 1. Prepare the trunk for the next minor release [[br]][[br]] |
68 | | i. Update version number in `m4/version.m4`. Locate and change the |
69 | | below lines |
70 | | {{{ |
71 | | MY_VERSION_early([A], [B+1], [0], [true]) |
72 | | }}} |
73 | | i. Add an entry in `NEWS` |
74 | | {{{ |
75 | | version A.[B+1] (released NOT YET) |
76 | | }}} |
77 | | The date is set when version A.[B+1] is released. [[br]][[br]] |
78 | | i. Commit changes to the repository, |
79 | | `svn ci -m "Bumping VERSION to A.[B+1]"` [[br]][[br]] |
80 | | |
81 | | === Rolling a minor release === |
82 | | Before you start, make sure you have write access to sourceforge page and that |
83 | | you can create checksum files, i.e., you need `openssl` and `md5`/`md5sum`. |
84 | | |
85 | | 1. Create a new milestone for next patch release A.B.1. |
86 | | 1. Make sure that all commits are performed into to the trunk, such |
87 | | as bumping version number(s) ([source:trunk/m4/version.m4 version.m4]), |
88 | | acknowledge contributions ([source:trunk/THANKS THANKS]), update |
89 | | file [source:trunk/NEWS NEWS]. |
90 | | [[br]][[br]] |
91 | | i. Update version number in `m4/version.m4`. |
92 | | Locate and change the below line |
93 | | {{{ |
94 | | MY_VERSION_early([A], [B], [0], [false]) |
95 | | }}} |
96 | | i. Update [source:trunk/THANKS THANKS]. [[br]][[br]] |
97 | | i. Set the date for the new release in [source:trunk/NEWS NEWS] |
98 | | {{{ |
99 | | version A.B (released 26 June 2007) |
100 | | }}} |
101 | | Make sure that the items in [source:trunk/NEWS NEWS] cover the new |
102 | | features of the release. [[br]][[br]] |
103 | | i. Commit changes to the repository |
104 | | {{{ |
105 | | svn ci -m "Preparing release A.B" |
106 | | }}} |
107 | | 1. Update copyright statements with commands |
108 | | {{{ |
109 | | make |
110 | | ./bin/svncopyright -v |
111 | | }}} |
112 | | Examine the updates and commit changes with `svn ci -m "updating |
113 | | copyright statements"`[[br]][[br]] |
114 | | 1. Issue `svn update` to make entire wc to be in revision `HEAD`. |
115 | | Needless to say, make sure that the program is in a state to be |
116 | | released; make sure that all the tests pass, test the distribution |
117 | | package, and perform all other release tests you think is |
118 | | appropriate.[[br]][[br]] |
119 | | Run |
120 | | {{{ |
121 | | make all |
122 | | ./build_support/tag_and_release.sh |
123 | | }}} |
124 | | Fix potential problems.[[br]][[br]] |
125 | | 1. Update SubversionCheckout and [wiki:WikiStart WikiStart][[br]][[br]] |
126 | | i. Update the section '''Latest stable release''' to reflect the new |
127 | | version, that is [[br]][[br]] |
128 | | * Change the version number [[br]][[br]] |
129 | | * Update the package link to the new version [[br]][[br]] |
130 | | * Update link to NEWS file to `source:tags/A.B/NEWS` [[br]][[br]] |
131 | | i. In section '''svndigest ''latest release'' ''' update link to |
132 | | `[source:tags/A.B/NEWS NEWS]` and modify the svn commands to |
133 | | {{{ |
134 | | svn checkout http://dev.thep.lu.se/svndigest/svn/tags/A.B svndigest-A.B |
135 | | }}} |
136 | | {{{ |
137 | | svn switch http://dev.thep.lu.se/svndigest/svn/tags/A.B |
138 | | }}} |
139 | | i. In section '''svndigest ''stable'' ''' update link to |
140 | | `[milestone:"svndigest A.B.1" A.B.1]` and modify the svn commands to |
141 | | {{{ |
142 | | svn checkout http://dev.thep.lu.se/svndigest/svn/branches/A.B-stable svndigest-A.B |
143 | | }}} |
144 | | {{{ |
145 | | svn switch http://dev.thep.lu.se/svndigest/svn/branches/A.B-stable |
146 | | }}} |
147 | | i. In section '''svndigest ''devel'' ''' update link to |
148 | | `[milestone:"svndigest A.B+1" A.B+1]`.[[br]][[br]] |
149 | | i. On WikiStart update links ''source:branches/A.B-stable/doc/readme.txt'', |
150 | | ''source:tags/A.B/NEWS'', ''source:branches/A.B-stable/README'', |
151 | | and also make sure that list of features is up to |
152 | | date.[[br]][[br]] |
153 | | 1. Update the version list in Trac using the |
154 | | [http://dev.thep.lu.se/svndigest/admin/ticket/versions trac-admin tool].[[br]][[br]] |
155 | | 1. Close the [http://dev.thep.lu.se/svndigest/roadmap milestone] |
156 | | associated with the release and replace `head` with appropriate |
157 | | revision.[[br]][[br]] |
158 | | 1. Merge the release into the trunk. To avoid confusion and |
159 | | minimize the risk of loosing fixes, this step is only performed by |
160 | | the ''Merge Master''. [[br]][[br]] |
161 | | i. Go to a pristine trunk WC. |
162 | | {{{ |
163 | | cd /path/to/svndigest-trunk |
164 | | svn update |
165 | | svn diff |
166 | | }}} |
167 | | i. Merge changes into trunk WC. |
168 | | {{{ |
169 | | svn merge ^/branches/A.B-stable |
170 | | }}} |
171 | | i. Resolve all conflicts. Run tests and perform all other |
172 | | appropriate tests to make sure that the merge does not create |
173 | | havoc. Typically changes in `m4/version.m4` are problematic |
174 | | so check this file extra carefully.[[br]][[br]] |
175 | | i. Commit changes to the trunk branch. |
176 | | {{{ |
177 | | svn commit -m "Merged release A.B to the trunk." |
178 | | }}} |
179 | | 1. Prepare the minor branch for the first patch release [[br]][[br]] |
180 | | i. Update version number in `version.m4`. Locate and change the |
181 | | below line |
182 | | {{{ |
183 | | MY_VERSION_early([A], [B], [1], [true]) |
184 | | }}} |
185 | | i. Add an entry in `NEWS` |
186 | | {{{ |
187 | | version A.B.1 (released NOT YET) |
188 | | }}} |
189 | | The date is set when version A.B.1 is released. [[br]][[br]] |
190 | | i. Commit changes to the repository, |
191 | | `svn ci -m "Bumping version"` [[br]][[br]] |
192 | | 1. Send an announcement to svndigest-users@lists.sourceforge.net |
193 | | using `announment.txt` as template.[[br]][[br]] |
194 | | 1. [https://trac.macports.org/newticket Create a ticket] ''svndigest A.B'' with type=update, keywords="haspatch maintainer", and port=svndigest. |
195 | | Attach `Portfile.diff` to newly created ticket. |
196 | | |
197 | | == Patch release procedure == |
198 | | |
199 | | This section describes what to do when publishing a patch release A.B.C. |
200 | | Before you start, make sure you have write access to sourceforge page and that |
201 | | you can create checksum files, i.e., you need `openssl` and `md5`/`md5sum`. |
202 | | |
203 | | 1. Create a new milestone for next patch release A.B.C+1 |
204 | | 1. Make sure that all commits are performed into to the branch, such |
205 | | as bumping version number(s) (`version.m4`), acknowledge |
206 | | contributions (`THANKS`), update file `NEWS`. [[br]][[br]] |
207 | | i. Update version number in `m4/version.m4`. Locate and change the |
208 | | below line |
209 | | {{{ |
210 | | MY_VERSION_early([A], [B], [C], [false]) |
211 | | }}} |
212 | | i. Update `THANKS`. [[br]][[br]] |
213 | | i. Set the date for the new release in `NEWS` |
214 | | {{{ |
215 | | version A.B.C (released 27 June 2007) |
216 | | }}} |
217 | | Make sure that the items in `NEWS` cover all important bug fixes of the |
218 | | release. [[br]][[br]] |
219 | | i. Commit changes to the repository, `svn ci -m "Preparing release A.B.C"` |
220 | | [[br]][[br]] |
221 | | 1. Update copyright statements with commands[[br]][[br]] |
222 | | {{{ |
223 | | make |
224 | | ./bin/svncopyright -v |
225 | | }}} |
226 | | Examine the updates and commit changes with `svn ci -m "updating |
227 | | copyright statements"`.[[br]][[br]] |
228 | | 1. Issue `svn update` to make entire wc to be in revision `HEAD`. |
229 | | Needless to say, make sure that the program is in a state to be |
230 | | released; make sure that all the tests pass, test the distribution |
231 | | package, and perform all other release tests you think is |
232 | | appropriate:[[br]][[br]] |
233 | | Run |
234 | | {{{ |
235 | | make all |
236 | | ./build_support/tag_and_release.sh |
237 | | }}} |
238 | | Fix potential problems[[br]][[br]] |
239 | | 1. Update SubversionCheckout and [wiki:WikiStart WikiStart][[br]][[br]] |
240 | | i. Update the section '''Latest stable release''' to reflect the new |
241 | | version, that is [[br]][[br]] |
242 | | * Change the version number [[br]][[br]] |
243 | | * Update the package link to the new version [[br]][[br]] |
244 | | * Update link to NEWS file to `source:tags/A.B.C/NEWS` [[br]][[br]] |
245 | | i. In section '''svndigest ''latest release'' ''' update link to |
246 | | `[source:tags/A.B.C/NEWS NEWS]` and modify the svn commands to |
247 | | {{{ |
248 | | svn checkout http://dev.thep.lu.se/svndigest/svn/tags/A.B.C svndigest-A.B.C |
249 | | }}} |
250 | | {{{ |
251 | | svn switch http://dev.thep.lu.se/svndigest/svn/tags/A.B.C |
252 | | }}} |
253 | | i. In section '''svndigest ''stable'' ''' update link to |
254 | | `[milestone:"svndigest A.B.[C+1]" A.B.[C+1]]`.[[br]][[br]] |
255 | | i. On WikiStart update reference to explicit latest version number, |
256 | | and links `[source:tags/A.B.C/NEWS NEWS]`.[[br]][[br]] |
257 | | 1. Close the milestone associated with the release and replace |
258 | | `head` with appropriate revision in log link. |
259 | | 1. Update the version list in Trac using the |
260 | | [http://dev.thep.lu.se/svndigest/admin/ticket/versions trac-admin tool].[[br]][[br]] |
261 | | 1. Merge the patch release into the trunk. To avoid confusion and |
262 | | minimize the risk of loosing fixes, this step is only performed by |
263 | | the Merge Master. [[br]][[br]] |
264 | | i. go to a pristine trunk WC |
265 | | {{{ |
266 | | cd /path/to/svndigest-trunk |
267 | | svn update |
268 | | svn diff |
269 | | }}} |
270 | | i. Merge changes into trunk. In this example the diffence between a |
271 | | minor release tag and the first patch release tag is merged into |
272 | | the trunk WC |
273 | | {{{ |
274 | | svn merge ^/branches/A.B-stable |
275 | | }}} |
276 | | i. Resolve all conflicts. Run tests and perform all other |
277 | | appropriate tests to make sure that the merge does not create |
278 | | havoc. Note, changes in `version.m4` should typically not be |
279 | | merged into trunk.[[br]][[br]] |
280 | | i. Commit changes to the trunk branch. |
281 | | {{{ |
282 | | svn commit -m "Merged patch release A.B.1 to the trunk. Delta A.B.1 - A.B" |
283 | | }}} |
284 | | 1. Prepare the minor branch for the next patch release [[br]][[br]] |
285 | | i. Update version number in `m4/version.m4`. Locate and change the |
286 | | below line |
287 | | {{{ |
288 | | MY_VERSION_early([A], [B], [C+1], [true]) |
289 | | }}} |
290 | | i. Add an entry in `NEWS` |
291 | | {{{ |
292 | | version A.B.[C+1] (released DATE) |
293 | | }}} |
294 | | The date is set when version A.B.[C+1] is released. [[br]][[br]] |
295 | | i. Commit changes to the repository, |
296 | | `svn ci -m "Changes for future release A.B.[C+1]"` [[br]][[br]] |
297 | | 1. Send an announcement to svndigest-users@lists.sourceforge.net |
298 | | using `announcement.txt` as template.[[br]][[br]] |
299 | | 1. [https://trac.macports.org/newticket Create a ticket] ''svndigest A.B.C'' with type=update, keywords="haspatch maintainer", and port=svndigest. |
300 | | Attach `Portfile.diff` to newly created ticket. |
| 1 | This document has been moved to [source:trunk/README.developer README.developer] |