CHECKLST.txt

   1 Checklists for PuTTY administrative procedures
   2 ==============================================
   3
   4 Going into pre-release stabilisation
   5 ------------------------------------
   6
   7 When we begin to work towards a release and want to enabling
   8 pre-releases on the website:
   9
  10  - Make a branch whose tip will be the current state of the
  11    pre-release. Regardless of whether the branch is from master or
  12    from a prior release branch, the name of the branch must now be in
  13    the form 'pre-X.YZ', or else the website will fail to link to it
  14    properly in gitweb and the build script will check out the wrong
  15    thing.
  16
  17  - Edit ~/adm/puttysnap.sh on my build machine to set $prerelver correctly.
  18
  19  - Edit ~/adm/puttysnap.sh on the master machine to enable pre-release
  20    builds, by changing the 'if false' to 'if true'.
  21
  22  - Put the website into pre-release mode, by defining prerel_version()
  23    in components/Base.mc to return the upcoming version number. Also
  24    add a news announcement in components/news. (Previous naming
  25    convention has been to name it in the form 'X.YZ-pre.mi'.)
  26
  27 Preparing to make a release
  28 ---------------------------
  29
  30 Now that PuTTY is in git, a lot of the release preparation can be done
  31 in advance, in local checkouts, and not pushed until the actual
  32 process of _releasing_ it.
  33
  34 To begin with, before dropping the tag, make sure everything is ready
  35 for it:
  36
  37  - First of all, go through the source (including the documentation),
  38    and the website, and review anything tagged with a comment
  39    containing the word XXX-REVIEW-BEFORE-RELEASE.
  40    (Any such comments should state clearly what needs to be done.)
  41
  42  - Also, do some testing of the Windows version with Minefield, and
  43    of the Unix version with valgrind or efence or both. In
  44    particular, any headline features for the release should get a
  45    workout with memory checking enabled!
  46
  47  - Double-check that we have removed anything tagged with a comment
  48    containing the words XXX-REMOVE-BEFORE-RELEASE or
  49    XXX-REVIEW-BEFORE-RELEASE. ('git grep XXX-RE' should only show up
  50    hits in this file itself.)
  51
  52  - Now update the version numbers and the transcripts in the docs, by
  53    checking out the release branch and running
  54
  55       make distclean
  56       ./release.pl --version=X.YZ --setver
  57
  58    Then check that the resulting automated git commit has updated the
  59    version number in the following places:
  60
  61     * putty/LATEST.VER
  62     * putty/doc/plink.but
  63     * putty/doc/pscp.but
  64     * putty/windows/putty.iss (four times, on consecutive lines)
  65
  66    and also check that it has reset the definition of 'Epoch' in
  67    Buildscr.
  68
  69  - Make the release tag, pointing at the version-update commit we just
  70    generated.
  71
  72  - If the release is on a branch (which I expect it generally will
  73    be), merge that branch to master.
  74
  75  - Write a release announcement (basically a summary of the changes
  76    since the last release). Squirrel it away in
  77    thyestes:src/putty-local/announce-<ver> in case it's needed again
  78    within days of the release going out.
  79
  80  - Update the website, in a local checkout:
  81     * Write a release file in components/releases which identifies the
  82       new version, a section for the Changes page, and a news
  83       announcement for the front page.
  84        + The one thing this can't yet contain is the release date;
  85          that has to be put in at the last minute, when the release
  86          goes live. Fill in 'FIXME', for the moment.
  87     * Disable the pre-release sections of the website (if previously
  88       enabled), by editing prerel_version() in components/Base.mc to
  89       return undef.
  90
  91  - Update the wishlist, in a local checkout:
  92     * If there are any last-minute wishlist entries (e.g. security
  93       vulnerabilities fixed in the new release), write entries for
  94       them.
  95     * If any other bug fixes have been cherry-picked to the release
  96       branch (so that the wishlist mechanism can't automatically mark
  97       them as fixed in the new release), add appropriate Fixed-in
  98       headers for those.
  99     * Add an entry to the @releases array in control/bugs2html.
 100
 101  - Make a release-candidate build from the release tag, and put the
 102    build.out and build.log dfiles somewhere safe. Normally I store
 103    these in an adjacent directory, so I'll run a command like
 104      bob -o ../X.YZ/build-X.YZ-rcN.out -l ../X.YZ/build-X.YZ-rcN.log -c X.YZ . RELEASE=X.YZ
 105    This should generate a basically valid release directory as
 106    `build-X.YZ-rcN.out/putty', and provide link maps and sign.sh
 107    alongside that.
 108
 109  - Double-check in build-X.YZ-rcN.log that the release was built from
 110    the right git commit.
 111
 112  - Do a bit of checking of the release binaries:
 113     * make sure they basically work
 114     * check they report the right version number
 115     * if there's any easily observable behaviour difference between
 116       the release branch and master, arrange to observe it
 117     * test the Windows installer
 118     * test the Unix source tarball.
 119
 120  - Sign the release: in the `build-X.YZ-rcN.out' directory, type
 121      sh sign.sh -r putty
 122    and enter the passphrases a lot of times.
 123
 124  - For my own safety, make the release candidate build read-only.
 125      chmod -R a-w build-X.YZ-rcN.out build-X.YZ-rcN.log
 126
 127 The actual release procedure
 128 ----------------------------
 129
 130 Once all the above preparation is done and the release has been built
 131 locally, this is the procedure for putting it up on the web.
 132
 133  - Make a final adjustment to your local website changes, filling in
 134    the release date in components/releases/X.YZ.mi.
 135
 136  - Upload the release itself and its link maps to everywhere it needs
 137    to be, by running this in the build.out directory:
 138       ../release.pl --version=X.YZ --upload
 139
 140  - Check that downloads via version-numbered URLs all work:
 141       ../release.pl --version=X.YZ --precheck
 142
 143  - Switch the 'latest' links over to the new release:
 144     * Update the HTTP redirect at the:www/putty/htaccess .
 145     * Update the FTP symlink at chiark:ftp/putty-latest .
 146
 147  - Now verify that downloads via the 'latest' URLs are all redirected
 148    correctly and work:
 149       ../release.pl --version=X.YZ --postcheck
 150
 151  - Push all the git repositories:
 152     * run 'git push' in the website checkout
 153     * run 'git push' in the wishlist checkout
 154     * push from the main PuTTY checkout. Typically this one will be
 155       pushing both the release tag and an update to the master branch,
 156       plus removing the pre-release branch, so you'll want some
 157       commands along these lines:
 158         git push origin master        # update the master branch
 159         git push origin --tags        # should push the new release tag
 160         git push origin :pre-X.YZ     # delete the pre-release branch
 161
 162  - Run ~/adm/puttyweb.sh on thyestes to update the website after all
 163    those git pushes.
 164
 165  - Check that the unpublished website on thyestes looks sensible.
 166
 167  - Run webupdate, so that all the changes on thyestes propagate to
 168    chiark. Important to do this _before_ announcing that the release
 169    is available.
 170
 171  - After running webupdate, run update-rsync on chiark and verify that
 172    the rsync mirror package (~/ftp/putty-website-mirror) contains a
 173    subdirectory for the new version and that the links from its
 174    latest.html point into that subdirectory.
 175
 176  - Announce the release!
 177     + Construct a release announcement email whose message body is the
 178       announcement written above, and which includes the following
 179       headers:
 180        * Reply-To: <putty@projects.tartarus.org>
 181        * Subject: PuTTY X.YZ is released
 182     + Mail that release announcement to
 183       <putty-announce@lists.tartarus.org>.
 184     + Post it to comp.security.ssh.
 185     + Mention it in <TDHTT> on mono.
 186
 187  - Edit the master ~/adm/puttysnap.sh to disable pre-release builds,
 188    if they were previously enabled.
 189
 190  - Relax (slightly).