CHECKLST.txt

   1 Checklists for PuTTY administrative procedures
   2 ==============================================
   3
   4 Locations of the licence
   5 ------------------------
   6
   7 The PuTTY copyright notice and licence are stored in quite a few
   8 places. At the start of a new year, the copyright year needs
   9 updating in all of them; and when someone sends a massive patch,
  10 their name needs adding in all of them too.
  11
  12 The LICENCE file in the main source distribution:
  13
  14  - putty/LICENCE
  15
  16 The resource files:
  17
  18  - putty/windows/pageant.rc
  19     + the copyright date appears twice, once in the About box and
  20       once in the Licence box. Don't forget to change both!
  21  - putty/windows/puttygen.rc
  22     + the copyright date appears twice, once in the About box and
  23       once in the Licence box. Don't forget to change both!
  24  - putty/windows/win_res.rc2
  25     + the copyright date appears twice, once in the About box and
  26       once in the Licence box. Don't forget to change both!
  27  - putty/windows/version.rc2
  28     + the copyright date appears once only.
  29  - putty/unix/gtkdlg.c
  30     + the copyright date appears twice, once in the About box and
  31       once in the Licence box. Don't forget to change both!
  32
  33 The documentation (both the preamble blurb and the licence appendix):
  34
  35  - putty/doc/blurb.but
  36  - putty/doc/licence.but
  37
  38 Preparing to make a release
  39 ---------------------------
  40
  41 Now that PuTTY is in git, a lot of the release preparation can be done
  42 in advance, in local checkouts, and not pushed until the actual
  43 process of _releasing_ it.
  44
  45 To begin with, before dropping the tag, make sure everything is ready
  46 for it:
  47
  48  - First of all, go through the source (including the documentation),
  49    and the website, and review anything tagged with a comment
  50    containing the word XXX-REVIEW-BEFORE-RELEASE.
  51    (Any such comments should state clearly what needs to be done.)
  52
  53  - Also, do some testing of the Windows version with Minefield, and
  54    of the Unix version with valgrind or efence or both. In
  55    particular, any headline features for the release should get a
  56    workout with memory checking enabled!
  57
  58  - Double-check that we have removed anything tagged with a comment
  59    containing the words XXX-REMOVE-BEFORE-RELEASE or
  60    XXX-REVIEW-BEFORE-RELEASE. ('git grep XXX-RE' should only show up
  61    hits in this file itself.)
  62
  63  - Now update the version numbers and the transcripts in the docs, by
  64    checking out the release branch and running
  65
  66       make distclean
  67       ./release.pl --version=X.YZ --setver
  68
  69    Then check that the resulting automated git commit has updated the
  70    version number in the following places:
  71
  72     * putty/LATEST.VER
  73     * putty/doc/plink.but
  74     * putty/doc/pscp.but
  75     * putty/windows/putty.iss (four times, on consecutive lines)
  76
  77    and also check that it has reset the definition of 'Epoch' in
  78    Buildscr.
  79
  80  - Make the release tag, pointing at the version-update commit we just
  81    generated.
  82
  83  - If the release is on a branch (which I expect it generally will
  84    be), merge that branch to master.
  85
  86  - Write a release announcement (basically a summary of the changes
  87    since the last release). Squirrel it away in
  88    atreus:src/putty-local/announce-<ver> in case it's needed again
  89    within days of the release going out.
  90
  91  - Update the website, in a local checkout:
  92     * Write a release file in components/releases which identifies the
  93       new version, its release date, a section for the Changes page,
  94       and a news announcement for the front page.
  95     * Disable the pre-release sections of the website (if previously
  96       enabled), by editing prerel_version() in components/Base.mc to
  97       return undef.
  98
  99  - Update the wishlist, in a local checkout:
 100     * If there are any last-minute wishlist entries (e.g. security
 101       vulnerabilities fixed in the new release), write entries for
 102       them.
 103     * If any other bug fixes have been cherry-picked to the release
 104       branch (so that the wishlist mechanism can't automatically mark
 105       them as fixed in the new release), add appropriate Fixed-in
 106       headers for those.
 107     * Add an entry to the @releases array in control/bugs2html.
 108
 109  - Build the release, by checking out the release tag:
 110      git checkout 0.XX
 111      bob . RELEASE=0.XX
 112    This should generate a basically valid release directory as
 113    `build.out/putty', and provide link maps and sign.sh alongside that
 114    in build.out.
 115
 116  - Double-check in build.log that the release was built from the right
 117    git commit.
 118
 119  - Do a bit of checking of the release binaries:
 120     * make sure they basically work
 121     * check they report the right version number
 122     * if there's any easily observable behaviour difference between
 123       the release branch and master, arrange to observe it
 124     * test the Windows installer
 125     * test the Unix source tarball.
 126
 127  - Sign the release: in the `build.out' directory, type
 128      sh sign.sh -r putty
 129    and enter the passphrases a lot of times.
 130
 131 The actual release procedure
 132 ----------------------------
 133
 134 Once all the above preparation is done and the release has been built
 135 locally, this is the procedure for putting it up on the web.
 136
 137  - Upload the release itself and its link maps to everywhere it needs
 138    to be, by running this in the build.out directory:
 139       ../release.pl --version=X.YZ --upload
 140
 141  - Check that downloads via version-numbered URLs all work:
 142       ../release.pl --version=X.YZ --precheck
 143
 144  - Switch the 'latest' links over to the new release:
 145     * Update the HTTP redirect at the:www/putty/htaccess .
 146     * Update the FTP symlink at chiark:ftp/putty-latest .
 147
 148  - Now verify that downloads via the 'latest' URLs are all redirected
 149    correctly and work:
 150       ../release.pl --version=X.YZ --postcheck
 151
 152  - Push all the git repositories:
 153     * run 'git push' in the website checkout
 154     * run 'git push' in the wishlist checkout
 155     * push from the main PuTTY checkout. Typically this one will be
 156       pushing both the release tag and an update to the master branch,
 157       plus removing the pre-release branch, so you'll want some
 158       commands along these lines:
 159         git push origin master        # update the master branch
 160         git push origin --tags        # should push the new release tag
 161         git push origin :pre-0.XX     # delete the pre-release branch
 162
 163  - Run ~/adm/puttyweb.sh on atreus to update the website after all
 164    those git pushes.
 165
 166  - Check that the unpublished website on atreus looks sensible.
 167
 168  - Run webupdate, so that all the changes on atreus propagate to
 169    chiark. Important to do this _before_ announcing that the release
 170    is available.
 171
 172  - After running webupdate, run update-rsync on chiark and verify that
 173    the rsync mirror package (~/ftp/putty-website-mirror) contains a
 174    subdirectory for the new version and mentions it in its .htaccess.
 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 ~/adm/puttysnap.sh to disable pre-release builds, if they were
 188    previously enabled.
 189
 190  - Relax (slightly).