Debian Codegraph @

doc/html/_sources/imap/developer/releasing.rst.txt

raw
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.