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