1.. _imap-developer-releasing: 2 3==================== 4Releasing Cyrus IMAP 5==================== 6 7.. contents:: 8 9These instructions are specifically for doing releases from branches that 10contain RST-based documentation and infrastructure. This includes 2.5 and 11later versions. 12 13For new releases from ancient branches, see :ref:`imap-developer-ancient-releasing` 14 15 16Prerequisites 17============= 18 19.. startblob releaseprereqs 20 21You will need a GPG key that you can use for signing. Ellie doesn't remember 22off the top of her head how to create one of these, so for now just read the 23manual like she did. :) 24 25Once you have a GPG key, it's helpful to upload your public key to 26`the MIT key-server <http://pgp.mit.edu>`_ 27 28And you need permission to send to the cyrus-announce mailing list. 29 30.. endblob releaseprereqs 31 32Order of operations 33=================== 34 35Sometimes you're releasing several new versions all at once(ish), for example 36maybe there's been a security fix that affected 2.4, 2.5 and 3.0. 37 38Github's release page will put a "Latest Release" graphic on the release with 39the newest tag (by timestamp, I think). This means that, if you're doing new 40releases for several different versions, you want to do the oldest one first, 41and only do the release for the current-stable branch last. 42 43If you start at the current stable branch and then work your way backwards 44through the older ones, you'll get Github saying "2.5.15 is the Latest 45Release" even though 3.0.13 was also just released... so, even though 46releasing the current-stable fix feels more urgent, suck it up and get the 47older-branch ones out first. 48 49 50Release notes 51============= 52 53Write up the release notes, and add them to the appropriate location under 54``docsrc/imap/download/release-notes/``. They will not yet be linked up. 55 56Commit and push your changes, and then wait for cyrusimap.org to rebuild 57(happens each hour, and takes a few mins, so check at about 5 past). The 58new release notes will be available at their direct URL -- easiest way to 59find it is to browse to some earlier version's release notes, then change 60version in the address bar to load up the new one. Confirm that they are 61correct and complete. 62 63 64Pre-release testing 65=================== 66 671. Ensure your git repository is clean, using something like ``git clean -xfd``. 68 Note that this command will destroy any uncommitted work you might have, 69 so make sure your ducks are in line before proceeding. 702. Generate a configure script: ``autoreconf -i -s`` 713. Generate everything else: ``./configure --enable-maintainer-mode`` (you do not 72 need any other options at this stage). 734. Run ``make distcheck``. This will generate a distribution tarball, and 74 test it in various ways. It takes about 10-15 mins to run, depending on 75 your hardware. If this command fails*, you are not ready to release -- 76 fix the problems, get them tested and committed, then restart the 77 pre-release testing. 785. ``make distcheck`` can only test so much (it doesn't know about cunit or 79 cassandane), so you also need to check the tarball against those. 80 81 i. The tarball will be called something like ``cyrus-imapd-3.0.0-rc2-23-g0241b22.tar.gz`` 82 (this corresponds to the ``git describe`` output). 83 ii. Extract it: ``tar xfz cyrus-imapd-*.tar.gz`` (substitute version for ``*``). 84 iii. Change into the directory: ``cd cyrus-imapd-*`` 85 iv. Configure it: ``./configure [...]`` (provide the same arguments you would 86 when building for Cassandane at any other time). 87 v. Compile it: ``make -j4`` -- it should build correctly. 88 vi. Run the unit tests: ``make -j4 check`` -- they should pass. 89 vii. Install it to your Cassandane prefix: ``make install`` 90 viii. Then run Cassandane normally -- it should pass. 91 ix. If any of this fails, fix it, commit it, then restart the pre-release 92 testing. 93 94.. Note:: 95 ``make distcheck`` doesn't work on the 2.5 branch. For 2.5, just use 96 ``make dist`` instead. 97 98.. Note:: 99 Realistically, there's usually some set of expected Cassandane failures 100 from each Cyrus branch, especially for 2.5. If you're doing releases 101 regularly, you've probably got a good gut feel for which failures are a 102 problem and which ones are just "that old thing". If you don't do 103 releases regularly, try to pull in someone who does for guidance about 104 which failures are ignorable, and which should be a source of stress. 105 106 If in doubt, try building and testing the previous release from the same 107 series, and compare the test results. 108 109 110Linking up release notes 111======================== 112 113The linkage of release notes is handled in ``docsrc/conf.py``. There's a bunch 114of places it needs to be updated. We should iterate these in detail at some 115point, but for now the easiest thing to do is look for lines containing the 116previous version and, if it makes sense to do so, update them to contain the 117new version. 118 119After this change is committed and pushed upstream, the cyrusimap.org website 120will start showing the new version as the "current" version at the next hourly 121update. So ellie likes to do this step at about 5-10 past the hour, which then 122gives her 50 minutes to finish the rest of the release process without the 123website updating before the downloads are available. 124 125 126Version tagging 127=============== 128 129Note: it is absolutely critical that your repository is clean and your local 130commits have been pushed upstream at this point. If they are not, and if 131anybody else pushes in the meantime, you will end up with a mess. 132 1331. Ensure your repository is clean again: ``git clean -xfd`` 1342. Create a signed, annotated tag for the new version: ``git tag -s cyrus-imapd-<version>`` 1353. You will be prompted to enter a commit message for the tag. I use the 136 following, just because it's what the old instructions said:: 137 138 We are pleased to announce the release of Cyrus IMAP version <version>. 139 140 This release contains features and fixes you can find on the following pages: 141 142 [paste link to the release notes for this version here] 143 1444. You will also be prompted to enter the pass phrase for your GPG key, do it. 1455. Generate a configure script: ``autoreconf -i -s`` 1466. Generate everything else: ``./configure --enable-maintainer-mode`` 1477. Create the distribution tarball: ``make distcheck`` (yes, again! this time 148 will have the correct version, now that you've tagged it.) 1498. If anything goes wrong up to here, delete the tag, fix the issue, and start 150 again from scratch. 1519. Sign the distribution tarball: ``gpg --sign -b cyrus-imapd-<version>.tar.gz`` 15210. Ellie also likes to copy the tarball and signature file somewhere safe, 153 just in case something happens between now and uploading. 15411. Push the tag upstream: ``git push ci cyrus-imapd-<version>`` (assuming your 155 remote is named "ci"). 156 157 158Inter-version website consistency 159================================= 160 161The website is built from an amalgamation of documentation from: 162 163* The current stable cyrus-imapd branch (top level) 164* The current master cyrus-imapd branch (``/dev`` hierarchy) 165* Each of the following cyrus-imapd branches (``/x.y`` hierarchies) 166 167 - cyrus-imapd-2.5 168 - cyrus-imapd-3.0 169 - cyrus-imapd-3.2 170 171* The current master cyrus-sasl branch (``/sasl`` hierarchy) 172 173When making a cyrus-imapd release, you need to add the new release notes 174file to each relevant cyrus-imapd branch. You also need to check and 175update the contents of ``docsrc/conf.py`` on each branch AND the cyrus-sasl 176repository. 177 178Sometimes you can just cherry-pick the commits around, but note that the 1792.5 website stores release notes files in a different path, so if you 180bother to copy release notes back to this branch, a naive cherry-pick will 181not put them in the right place! 182 183This step often gets forgotten, so if you actually follow it, and notice 184some missing versions, just go ahead and add them while you're there. 185 186Uploading 187========= 188 189.. Note:: 190 This section does NOT apply to releases from the master branch. We 191 do not publish release tarballs for those. People running master code 192 are expected to use a git checkout. 193 194Time to upload the release tarball and signature file! 195 1961. Navigate to https://github.com/cyrusimap/cyrus-imapd/releases 1972. The tag you pushed earlier will now be available as a release, but it will 198 have very little information about it 1993. Click on the tag name 2004. Click "Edit tag" on the right 2015. *Leave every field on the page as it is (probably blank!), except*: 2026. Use the "Attach binaries by dropping them here or selecting them" widget 203 to upload the tarball and signature files 2047. If this is an alpha/beta/rc release, click the "This is a pre-release" 205 checkbox 2068. Click "Save". The commit message from the tag annotation will be used 207 as the release description. 208 209Tell the world 210============== 211 2121. Send an announcement to the info-cyrus and cyrus-announce lists. 213