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