docs/internals/release-HOWTO.txt

   1 -----------------------------------------------------------------------------
   2 TODO list when doing a Valgrind release (with release number "X.Y.Z")
   3 -----------------------------------------------------------------------------
   4
   5 There are two kinds of releases:
   6
   7 - Feature releases:  X.Y.0, which can include new features.
   8
   9 - Bug-fix releases:  X.Y.[12...], which only include bug fixes.
  10
  11
  12 First of all:
  13
  14 - Tell valgrind-developers you want to do a release.  Give a timeframe for
  15   everyone to check in any final features/bug-fixes they want in the
  16   release.
  17
  18 - Go over the docs, make sure they're up to date.
  19
  20 - Update version number and date in configure.ac. Probably just the
  21   v_suffix_ver, set it to RC1. The v_rel_date probably won't be known yet,
  22   updating it is in the list below of tasks for the official release.
  23   Note that the date MUST be quoted with ["...date string..."].
  24
  25 - Make sure the after ./autogen.sh && ./configure
  26   __VALGRIND_MAJOR__ and __VALGRIND_MINOR__ are correct for the release.
  27   (include/valgrind.h)
  28   And that docs/xml/vg-entities.xml contains the correct release number
  29   and release date.
  30
  31 - Write release notes, add to NEWS.  Include a list of fixed bugs from
  32   Bugzilla.  It's unclear how to do this consistently.  The approach
  33   taken for 3.0.0 was to go to this page in KDE's bugzilla:
  34      http://bugs.kde.org/query.cgi
  35   and to create a search where
  36      "Status and severity" / Status field is set to RESOLVED
  37   and
  38      "Involved People" / Email, bug-owner contains "jseward"
  39   since I believe jseward@acm.org is the owner of all bugs.
  40   This creates a long list of bugs which does not conveniently stop
  41   at the previous release.  Work backwards through this list until
  42   either (1) you run out of patience, or (2) most of the bugs seem
  43   to pertain to previous releases and are now irrelevant.  In short
  44   this is not a very scientific or robust way to collect up all
  45   bugs fixed since last time.
  46
  47   Suggestion for next release: when a bug is fixed, update NEWS
  48   directly => less chance to forget, and NEWS always up to date
  49   in GIT.
  50
  51 - Other files that might need updating:  README, README_DEVELOPERS,
  52   README_PACKAGERS.
  53
  54 - Add X.Y.Z and X.Y+1.Z.GIT versions to Bugzilla.
  55
  56 - Add "wantedX.Y.Z+1" and "wantedX.Y+1.Z" milestones to Bugzilla.
  57
  58 - Check whether copyright years need updating.
  59   If so, run  auxprogs/change-copyright-year  in the top of the tree.
  60
  61 - Consider upgrading the C++ demangler.
  62   auxprogs/update-demangler   helps with that
  63
  64 - Consider upgrading zstd compression
  65   See README_DEVELOPERS for details.
  66
  67 - Contact Gregory Czajkowski ( gregczajkowski@yahoo.com ) and ask him
  68   to build (make && make check) valgrind with ICC.
  69
  70 For each release candidate (should do release candidates for feature
  71 releases, bug-fix-only releases might not need one):
  72
  73 - Build.
  74
  75 - Do pre-release testing:
  76
  77   * Check it builds and regtests on a vanilla gcc-2.96 / RedHat 7.3 distro.
  78   ??? is this really still up to date ???
  79
  80   * Check standard build and regtest on the following cpus:
  81        x86, sse2 (P4)
  82        x86, sse1 (PIII)
  83        x86, no sse (eg older VIA C3s, or perhaps even Pentium-MMX)
  84        amd64
  85        ppc32, altivec
  86        ppc32, no altivec (eg old iMac G3s)
  87
  88   * Check that the regression tests work on all platforms with more self checks:
  89      export EXTRA_REGTEST_OPTS="--sanity-level=4 --helgrind:hg-sanity-flags=011111"
  90      make regtest
  91
  92   * check there are no memleaks or similar bugs by running all regtests
  93     in an outer/inner setup (see README_DEVELOPERS).
  94
  95   * Check valgrind-listener works on all archs, also connecting to it
  96     from all archs.
  97
  98   * Check memcheck can run all the insn-set tests.  The testsuite
  99     only runs those on 'none', but memcheck looks at all primops, and I've
 100     been caught out by this before.  Basically all the programs in
 101     none/tests/{x86,amd64,ppc32}.
 102
 103   * Check XML output is still readable by Valkyrie and vk_logmerge tools
 104
 105   * Test with large applications (firefox and OOo 2.0) on all platforms.
 106
 107   * Run regression tests from gsl-1.6 on all platforms.  This is a good,
 108     thorough test of FP.  Easy, using the scripts auxprogs/gsl16test.
 109
 110   * s390x: Run regression tests on a z900 machine. That is the oldest
 111     supported model and there is no nightly build for it.
 112
 113   * s390x: Ensure README.s390 is up-to-date and URLs therein are not stale.
 114
 115 - Change release number (v_major_ver, v_minor_ver, v_micro_ver)
 116   in configure.ac, set v_suffix_ver to RCN, where 'N' is the release
 117   candidate number. Don't forget to ./autogen.sh and ./configure afterwards.
 118
 119 - Make the tarball ("make dist") and put it on the web somewhere (it doesn't
 120   have to be on valgrind.org if another site is easier).
 121   https://sourceware.org/pub/valgrind/ is the default release site now.
 122   You need a shell account on sourceware.org, then scp it with:
 123   scp valgrind-X.YY-RCN.tar.bz \
 124     USER@sourceware.org:/sourceware/ftp/pub/valgrind/
 125
 126 - Ensure the tarball builds, runs, regtests on the platforms of interest.
 127   However redundant this seems, sometimes it can be that a from-the-repo
 128   build works whereas a from-the-tarball one doesn't, usually due to some
 129   trivial installation problem.
 130
 131 - Also check the HTML and print docs look sane (eg. links work).  And the
 132   man pages, esp. that there are no broken references (look for "???").
 133
 134 - Announce the release:
 135   - Email valgrind-users and valgrind-developers (but not valgrind-announce).
 136   - Make clear it's a release candidate.
 137   - Make sure you tell everyone where to download from.
 138   - Include the release notes in the email (maybe not necessary for release
 139     candidates 2+).
 140
 141 - Wait 2--3 days for feedback.  If bugs appear:
 142   - Fix them.
 143   - Update the bug-fix list in NEWS if necessary.
 144   - Do another release candidate.
 145
 146
 147 For the official release:
 148
 149 - Again, update date (v_rel_date) in configure.ac for the official release
 150   date and set v_suffix_ver to empty [] in configure.ac.
 151
 152 - Do pre-release testing:
 153   - Make sure regtests run ok on all platforms of interest.
 154   - Make sure Mozilla and OpenOffice run ok on all platforms of interest.
 155
 156 - Run ./autogen.sh && ./configure && make dist to make the tarball.
 157
 158 - Check tarball builds, installs, regtests on platforms of interest.
 159   If not, fix and repeat until success.
 160
 161 - Tag the repository ("VALGRIND_X_Y_Z").
 162
 163   If it's a X.Y.0 release, make "VALGRIND_X_Y_BRANCH" branch, too.
 164   Useful examples (X.Y.0 major release):
 165
 166     cd valgrind
 167     git checkout HEAD
 168     git tag VALGRIND_3_3_0
 169     git branch VALGRIND_3_3_BRANCH
 170     git push
 171
 172   (X.Y.Z minor release):
 173
 174     cd valgrind
 175     git checkout VALGRIND_3_6_BRANCH
 176     git tag VALGRIND_3_6_1
 177     git push
 178
 179
 180 - Update website:
 181   - Put the tarball up.
 182   - Update the docs -- both the tarball'd docs, and the online-readable docs.
 183   - Update www.valgrind.org/downloads/current.html.
 184   - Update www.valgrind.org/downloads/old.html.
 185   - Add a news item to the front page and also to valgrind.org/info/news.html.
 186     Include a link to the release notes.  Possibly remove any old release
 187     notices form the front page.
 188   - Update the "release-date" and "release-version" in php/.htconfx.
 189   - Other pages that might need updating:  downloads/repository.html.
 190
 191 - Change release number in configure.ac with v_minor_ver one more than the
 192   release just done. Set v_suffix_ver to [GIT].
 193
 194 - Make sure the release notes are present in the NEWS file on the master and
 195   the branch.
 196
 197 - Announce the release:
 198   - Email valgrind-users, valgrind-developers, and valgrind-announce.
 199   - Email Linux Weekly News.
 200   - Include the release notes in the email.
 201
 202 - Go on holiday.