| 1 |
.. _imap-developer-releasing: |
| 2 |
|
| 3 |
====================================== |
| 4 |
Releasing Cyrus IMAP - normal releases |
| 5 |
====================================== |
| 6 |
|
| 7 |
.. contents:: |
| 8 |
|
| 9 |
These instructions are specifically for doing point releases. Those are |
| 10 |
releases that change the *z* in ``x.y.z``. |
| 11 |
|
| 12 |
For snapshot releases from the master branch, see |
| 13 |
:ref:`imap-developer-snapshot-releasing` |
| 14 |
|
| 15 |
For major (x.y) releases, you will follow this process for publishing the |
| 16 |
release tarballs, but there are additional steps before and around that, |
| 17 |
detailed at :ref:`imap-developer-major-releasing`. |
| 18 |
|
| 19 |
Prerequisites |
| 20 |
============= |
| 21 |
|
| 22 |
.. startblob releaseprereqs |
| 23 |
|
| 24 |
You will need a GPG key that you can use for signing. Ellie doesn't remember |
| 25 |
off the top of her head how to create one of these, so for now just read the |
| 26 |
manual like she did. :) |
| 27 |
|
| 28 |
Once you have a GPG key, it's helpful to upload your public key to |
| 29 |
`the MIT key-server <http://pgp.mit.edu>`_ |
| 30 |
|
| 31 |
And you need permission to send to the cyrus-announce mailing list. |
| 32 |
|
| 33 |
.. endblob releaseprereqs |
| 34 |
|
| 35 |
Order of operations |
| 36 |
=================== |
| 37 |
|
| 38 |
Sometimes you're releasing several new versions all at once(ish), for example |
| 39 |
maybe there's been a security fix that affected 3.12, 3.10 and 3.8. (Heaven |
| 40 |
forbid.) |
| 41 |
|
| 42 |
Github's release page will put a "Latest Release" graphic on the release with |
| 43 |
the newest tag (by timestamp, I think). This means that, if you're doing new |
| 44 |
releases for several different versions, you want to do the oldest one first, |
| 45 |
and only do the release for the current-stable branch last. |
| 46 |
|
| 47 |
If you start at the current stable branch and then work your way backwards |
| 48 |
through the older ones, you'll get Github saying "3.8.15 is the Latest |
| 49 |
Release" even though 3.12.3 was also just released... so, even though |
| 50 |
releasing the current-stable fix feels more urgent, suck it up and get the |
| 51 |
older-branch ones out first. |
| 52 |
|
| 53 |
|
| 54 |
Release notes |
| 55 |
============= |
| 56 |
|
| 57 |
Write up the release notes, and add them to the appropriate location under |
| 58 |
``docsrc/imap/download/release-notes/``. They will not yet be linked up. |
| 59 |
Build the documentation locally with ``make doc-html``, then check the new |
| 60 |
release notes file in your brower to make sure it's correct and complete. |
| 61 |
It will be in ``doc/html/imap/download/release-notes/...``. |
| 62 |
|
| 63 |
Commit the new release notes with a message like ``docs: release notes for |
| 64 |
cyrus-imapd <version>``, but don't push it yet. You might want to keep these |
| 65 |
release commits on a separate branch for now, so you can rebase it if the real |
| 66 |
branch changes along the way. |
| 67 |
|
| 68 |
Pre-release testing |
| 69 |
=================== |
| 70 |
|
| 71 |
1. Ensure your git repository is clean, using something like ``git clean -dfx``. |
| 72 |
Note that this command will destroy any uncommitted work you might have, |
| 73 |
so make sure your ducks are in line before proceeding. |
| 74 |
2. Generate a configure script: ``autoreconf -i -s`` |
| 75 |
3. Generate everything else: ``./configure --enable-maintainer-mode`` (you do not |
| 76 |
need any other options at this stage). |
| 77 |
4. Run ``make distcheck``. This will generate a distribution tarball, and |
| 78 |
test it in various ways. It takes about 10-15 mins to run, depending on |
| 79 |
your hardware. If this command fails*, you are not ready to release -- |
| 80 |
fix the problems, get them tested and committed, then restart the |
| 81 |
pre-release testing. |
| 82 |
5. ``make distcheck`` can only test so much (it doesn't know about cunit or |
| 83 |
cassandane), so you also need to check the tarball against those. |
| 84 |
|
| 85 |
i. The tarball will be called something like ``cyrus-imapd-3.12.2-rc2-23-g0241b22.tar.gz`` |
| 86 |
(this corresponds to the ``git describe`` output). |
| 87 |
ii. Extract it: ``tar xfz cyrus-imapd-*.tar.gz`` (substitute version for ``*``). |
| 88 |
iii. Change into the directory: ``cd cyrus-imapd-*`` |
| 89 |
iv. Configure it: ``./configure [...]`` (provide the same arguments you would |
| 90 |
when building for Cassandane at any other time). |
| 91 |
v. Compile it: ``make -j4`` -- it should build correctly. |
| 92 |
vi. Run the unit tests: ``make -j4 check`` -- they should pass. |
| 93 |
vii. Install it to your Cassandane prefix: ``make install`` |
| 94 |
viii. Then run Cassandane normally -- it should pass. |
| 95 |
ix. If any of this fails, fix it, commit it, land it upstream, then |
| 96 |
restart the pre-release testing. |
| 97 |
|
| 98 |
.. Note:: |
| 99 |
Realistically, there's usually some set of expected Cassandane failures |
| 100 |
from each Cyrus branch. If you're doing releases regularly, you've |
| 101 |
probably got a good gut feel for which failures are a problem and which |
| 102 |
ones are just "that old thing". If you don't do releases regularly, try to |
| 103 |
pull in someone who does for guidance about which failures are ignorable, |
| 104 |
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 |
|
| 110 |
Linking up release notes |
| 111 |
======================== |
| 112 |
|
| 113 |
The linkage of release notes is handled in ``docsrc/conf.py``. There's a bunch |
| 114 |
of places it needs to be updated. We should iterate these in detail at some |
| 115 |
point, but for now the easiest thing to do is look for lines containing the |
| 116 |
previous version and, if it makes sense to do so, update them to contain the |
| 117 |
new version. |
| 118 |
|
| 119 |
Commit this on your WIP branch with a message like ``docs: cyrus-imapd |
| 120 |
<version> released``. This is usually the commit you'll end up tagging as the |
| 121 |
release. |
| 122 |
|
| 123 |
|
| 124 |
Version tagging |
| 125 |
=============== |
| 126 |
|
| 127 |
Note: it is critical that your local copy of the branch you'll be releasing to |
| 128 |
is clean and up to date, and that your WIP branch (if any) is a direct |
| 129 |
descendant of it, otherwise you may end up with a mess later. |
| 130 |
|
| 131 |
1. Ensure your repository is clean again: ``git clean -dfx`` |
| 132 |
2. Create a signed, annotated tag for the new version: ``git tag -s cyrus-imapd-<version>`` |
| 133 |
3. You will be prompted to enter a commit message for the tag. I use the |
| 134 |
following, just because it's what the old instructions said:: |
| 135 |
|
| 136 |
We are pleased to announce the release of Cyrus IMAP version <version>. |
| 137 |
|
| 138 |
This release contains features and fixes you can find on the following pages: |
| 139 |
|
| 140 |
[paste link to the release notes for this version here] |
| 141 |
|
| 142 |
4. You will also be prompted to enter the pass phrase for your GPG key, do it. |
| 143 |
5. Generate a configure script: ``autoreconf -i -s`` |
| 144 |
6. Generate everything else, this time with release checks enabled: |
| 145 |
``./configure --enable-maintainer-mode --enable-release-checks`` |
| 146 |
7. Create the distribution tarball: ``make distcheck`` (yes, again! this time |
| 147 |
will have the correct version, now that you've tagged it.) |
| 148 |
8. If anything goes wrong up to here, delete the tag, fix the issue, and start |
| 149 |
again from scratch. |
| 150 |
9. Sign the distribution tarball: ``gpg --sign -b cyrus-imapd-<version>.tar.gz`` |
| 151 |
10. Ellie also likes to copy the tarball and signature file somewhere safe, |
| 152 |
just in case something happens between now and uploading. |
| 153 |
11. If you've been using a WIP branch for the release notes and docsrc/conf.py |
| 154 |
changes, fast forward your commits onto the real branch and push it |
| 155 |
upstream. |
| 156 |
12. Push the tag upstream: ``git push ci cyrus-imapd-<version>`` (assuming your |
| 157 |
remote is named "ci"). |
| 158 |
|
| 159 |
|
| 160 |
Inter-version website consistency |
| 161 |
================================= |
| 162 |
|
| 163 |
The website is built from an amalgamation of documentation from: |
| 164 |
|
| 165 |
* The current stable cyrus-imapd branch (top level) |
| 166 |
* The current master cyrus-imapd branch (``/dev`` hierarchy) |
| 167 |
* The release-numbered cyrus-imapd branches (``/x.y`` hierarchies) |
| 168 |
* The current master cyrus-sasl branch (``/sasl`` hierarchy) |
| 169 |
|
| 170 |
When making a cyrus-imapd release, you need to add the new release notes |
| 171 |
file to each relevant cyrus-imapd branch, including master and the current |
| 172 |
stable branch. You also need to check and update the contents of |
| 173 |
``docsrc/conf.py`` on each branch AND the cyrus-sasl repository. |
| 174 |
|
| 175 |
For the cyrus-imapd branches, you can mostly just cherry-pick the two release |
| 176 |
commits around. The docsrc/conf.py changes may not pick cleanly to the master |
| 177 |
branch but it's not hard to figure out how to massage it. |
| 178 |
|
| 179 |
For cyrus-sasl, manually update its docsrc/conf.py with the correct cyrus-imapd |
| 180 |
version numbers, commit it with a similar message, and push it. If in doubt, |
| 181 |
have a look at previous commits that modified this file for inspiration. If |
| 182 |
you don't have push access to the cyrus-sasl repository, check with someone who |
| 183 |
does. |
| 184 |
|
| 185 |
This step sometimes gets forgotten, so if you actually follow it, and notice |
| 186 |
some missing versions, just go ahead and add them while you're there. |
| 187 |
|
| 188 |
Uploading |
| 189 |
========= |
| 190 |
|
| 191 |
.. Note:: |
| 192 |
This section does NOT apply to releases from the master branch. We |
| 193 |
do not publish release tarballs for those. People running master code |
| 194 |
are expected to use a git checkout. |
| 195 |
|
| 196 |
Time to upload the release tarball and signature file! |
| 197 |
|
| 198 |
1. Navigate to https://github.com/cyrusimap/cyrus-imapd/releases |
| 199 |
2. The tag you pushed earlier will now be available as a release, but it will |
| 200 |
have very little information about it |
| 201 |
3. Click on the tag name |
| 202 |
4. Click "Edit tag" on the right |
| 203 |
5. *Leave every field on the page as it is (probably blank!), except*: |
| 204 |
6. Use the "Attach binaries by dropping them here or selecting them" widget |
| 205 |
to upload the tarball and signature files |
| 206 |
7. If this is an alpha/beta/rc release, click the "This is a pre-release" |
| 207 |
checkbox |
| 208 |
8. Click "Save". The commit message from the tag annotation will be used |
| 209 |
as the release description. |
| 210 |
|
| 211 |
Tell the world |
| 212 |
============== |
| 213 |
|
| 214 |
1. Send an announcement to the info-cyrus and cyrus-announce lists. |