Debian Codegraph @

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

raw
1 .. _imap-developer-snapshot-releasing:
2
3 ==========================================
4 Releasing Cyrus IMAP - developer snapshots
5 ==========================================
6
7 .. contents::
8
9 These instructions describe the process of producing "developer snapshots"
10 from the master branch. These are tag-only releases: no release tarball
11 is published.
12
13 For normal point releases, see :ref:`imap-developer-releasing`
14
15 We haven't been doing this much, or very consistently. Consider this
16 document and process a work in progress, which we'll refine as we go.
17
18 You can look at the tag cyrus-imapd-3.3.1 and a few commits before it to
19 get a sense of the kind of things this process involves.
20
21 Prerequisites
22 =============
23
24 Same as for normal releases
25
26 Make sure master is good
27 ========================
28
29 With the master branch checked out and up to date:
30
31 1. Ensure your git repository is clean, using something like
32 ``git clean -xfd``. Note that this command will destroy any uncommitted
33 work you might have, so make sure your ducks are in line before proceeding.
34 2. Generate a configure script: ``autoreconf -i -s``
35 3. Generate everything else: ``./configure --enable-maintainer-mode`` (you do
36 not need any other options at this stage).
37 4. Run ``make distcheck``. This will generate a distribution tarball, and
38 test it in various ways. It takes about 10-15 mins to run, depending on
39 your hardware. If you usually build Cyrus with a script that sets PATH etc,
40 you will need to provide the same environment at this step. For example,
41 ellie uses an alias like this for this step:
42
43 ``alias distcheck="PATH=/usr/local/cyruslibs/bin:$PATH make distcheck"``.
44
45 If ``make distcheck`` fails, you are not ready to proceed -- fix the
46 problems, get them tested and committed, then restart this testing.
47 5. ``make distcheck`` can only test so much (it doesn't know about cunit or
48 cassandane), so you also need to check the tarball against those.
49
50 i. The tarball will be called something like
51 ``cyrus-imapd-3.0.0-rc2-23-g0241b22.tar.gz``
52 (this corresponds to the ``git describe`` output).
53 ii. Extract it: ``tar xfz cyrus-imapd-*.tar.gz``
54 (substitute version for ``*``).
55 iii. Change into the directory: ``cd cyrus-imapd-*``
56 iv. Configure it: ``./configure [...]`` (provide the same arguments and
57 environment that you would when building for Cassandane at any other
58 time).
59 v. Compile it: ``make -j4`` -- it should build correctly.
60 vi. Run the unit tests: ``make -j4 check`` -- they should pass.
61 vii. Install it to your Cassandane prefix: ``make install``
62 viii. Change into the `cassandane` directory within the extracted source
63 (not the git source!): ``cd cassandane``
64 ix. Build Cassandane's binary components: ``make -j4``
65 x. Run Cassandane: ``./testrunner.pl``
66 xi. If any of this fails, get it fixed and merged, then redo this testing
67
68 Mixed-version Cassandane testing
69 ================================
70
71 This is a good point to make sure that replication and murder setups can talk
72 to each other between versions.
73
74 1. Add `[cyrus murder]` and `[cyrus replica]` sections to your cassandane.ini
75 and configure each with their own prefix, different from your
76 `[cyrus default]` one. Check `cassandane/cassandane.ini.example` in the
77 repository for examples with comments. Do the same for `[cyrus backup]` if
78 you like -- it's not documented like the others, but it works the same way.
79 2. For each prefix you've configured, check out the Cyrus version you want to
80 run there, do a from-scratch complete build with
81 ``./configure --prefix=/the/prefix ...`` and install it
82 3. Do the same for your usual `[cyrus default]` prefix
83 4. Check out the version whose Cassandane you want to run. Rebuild Cassandane's
84 binary components with ``make -C cassandane/utils``
85 5. Run Cassandane -- the Replication, MurderIMAP, and MurderJMAP suites are
86 significant here, and the Backups suite if you configured `[cyrus backup]`.
87 6. Rinse and repeat for other combinations
88
89 You should do this in four combinations:
90
91 1. `[cyrus default]` built from master branch, others built from the current
92 stable branch, and running Cassandane from the master branch
93 2. Same as 1, but running Cassandane from the current stable branch
94 3. `[cyrus default]` built from the current stable branch, others built from
95 the master branch, and running Cassandane from the current stable branch
96 4. Same as 3, but running Cassandane from the master branch
97
98 lib/imapoptions
99 ===============
100
101 I'm not sure about whether we want to do this step at each snapshot, or
102 save it for a big batch at the next major release. The difference is
103 whether we conceptually treat these tags as releases of the feature or
104 not.
105
106 If we do do this:
107
108 Check through `lib/imapoptions` for options with `"UNRELEASED"` in any of
109 their version fields.
110
111 1. Replace these with the version number that this snapshot will be tagged
112 as.
113 2. If any have been missed, there will be warnings (in yellow) when trying
114 to (re)generate `lib/imapopts.c`. You can run
115 ``touch lib/imapoptions && make lib/imapopts.c`` to check
116
117 Release notes
118 =============
119
120 Snapshot release notes are like major x.y.0 release notes, in that they
121 contain a high-level overview of the new features/etc, but not a blow-by-blow
122 of every commit. They describe the changes since the *last stable series*,
123 which means the release notes for each subsequent snapshot start as a copy
124 of the previous, and reset only when a new stable series forks. The release
125 notes for the developer snapshots will form the starting point for the release
126 notes of the next major release.
127
128 Release notes live under ``docsrc/imap/download/release-notes/``.
129
130 1. Copy the release notes from the previous snapshot of this series into
131 a new file for this snapshot. If this is the first snapshot of the series,
132 then copy the `<series>.0-alpha0` release notes instead.
133 2. Review the contents of all the `changes/next/*` files. Flesh out the new
134 release notes document accordingly. (Compare previous `...-beta*` and
135 `x.y.0` release notes to get a sense of the tone and level of detail.)
136 3. Review `docsrc/imap/download/upgrade.rst`, also with reference to the
137 `changes/next/*` files. Make any necessary updates. We expect people
138 upgrading to the new version to follow these instructions, so they'd better
139 be as complete and correct as we can get them.
140 4. Review `docsrc/imap/rfc-support.rst`, also with reference to the
141 `changes/next/*` files, and make any necessary updates. Also compare this
142 file with the version of it on the stable branch. Check for any changes
143 that don't have an accompanying `changes/next` file, and if there are any,
144 also add suitable release notes and/or upgrade documentation for those.
145
146 Should the `changes/next` files be removed at this point? I'm not sure, we
147 have not done any snapshot releases since we started tracking changes like
148 that. The major releasing process assumes that this all happens as a big
149 bang before the x.y.0, but if we return to doing regular snapshots, we can
150 distribute that load over the year. If the `changes/next` files are removed
151 as they're integrated into a snapshot, that will be less confusing, but it
152 will be harder to do a holistic review later. Maybe they can be moved
153 aside somewhere instead of removed, to `changes/<snapshot-version>` or
154 something...
155
156 docsrc/conf.py
157 ==============
158
159 1. Update all the relevant version strings in `docsrc/conf.py`
160
161 check documentation
162 ===================
163
164 1. Make sure your RST changes are good: ``make doc-html``. Pay attention
165 to any errors or warnings (they will be coloured). There will be some
166 you can clearly ignore, such as glob patterns for future release notes
167 that don't exist yet, but do your best to deal with everything else.
168 The generated documentation will be under the `doc/html/` directory --
169 examine it in your browser to make sure all your formatting and such makes
170 sense.
171
172 PR and/or commit
173 ================
174
175 Once you're satisfied that you've done everything that needed doing here,
176 commit the changes to a branch and submit a PR. Historically we've usually
177 just made these changes directly on master, but since our workflow uses
178 PRs these days, let's try that.
179
180 Once the PR has been approved, rebase your branch on top of current master,
181 force-push it, and then "Merge" it through the GitHub UI.
182
183 Tag
184 ===
185
186 You'll want to apply the tag to the merge commit where the PR landed. Usually
187 this will be the head of master, but if there's been hang time between merging
188 the PR and starting this step, other merges might have snuck in on top of it.
189 That's fine, just be careful about which commit you're tagging.
190
191 1. Make sure your master branch is checked out, clean, and up to date
192 2. Create a signed, annotated tag declaring that this is now whatever version
193 it is:
194 ``git tag -s cyrus-imapd-<snapshot-version>``
195 3. You will be prompted to enter a commit message for the tag (this is
196 what makes it an "annotated" tag). Ellie uses something like
197 "Developer release <version>".
198 4. You will also be prompted to enter the pass phrase for your GPG key, do it.
199 5. It's a good idea to do a full build-and-test of a release tarball at this
200 point, just to make sure things are sane. Throw the tarball away when
201 you're done though, we don't publish it.
202 6. Push the new tag: ``git push ci cyrus-imapd-<snapshot-version>``
203
204 Fastmail specific: also push the new tag to the Fastmail repo.
205
206 Tell the world
207 ==============
208
209 1. Send an announcement to the cyrus-devel list.
210
211 Update this document
212 ====================
213
214 The process probably changed a little in practice. Update this document to
215 match reality!