binutils/README-how-to-make-a-release

   1                 README for MAKING BINUTILS RELEASES
   2
   3 This is a collection of notes on how to perform a binutils release.  A
   4 lot of this information can also be found in the maintain.texi file in
   5 the gnulib project:
   6
   7   https://www.gnu.org/software/gnulib/
   8
   9 It is useful to have a cloned copy of the sources of this project as
  10 it also contains an upload script used to install tarballs on the GNU
  11 FTP server.
  12
  13 Make sure that you have upload authority on sourceware and fencepost.
  14 Beware - this is an involved process and can take weeks to complete.
  15 See the maintain.texi file for details on how to obtain these
  16 permissions.
  17
  18 -------------------------------------------------
  19 How to perform a release.
  20 -------------------------------------------------
  21
  22   1. Send an email out warning contributors about the forthcoming
  23      branch.  Set a date for the branch (weekends are better because
  24      they are less busy).
  25
  26   2. When the branch date is near:  Update the libiberty and config
  27      directories and the top level configure files.
  28
  29   3. When branch day arrives add markers for the upcoming release to
  30      gas, ld, gold and binutils NEWS files.
  31        [If using the make-prerelease.sh script, check that
  32         common.sh has the right values].
  33        [make-prelease.sh command i]
  34        [make-prelease.sh command C]
  35      Likewise for all of the ChangeLog files.
  36      Add a note of the name of the new branch to binutils/BRANCHES.
  37      Commit these changes.
  38        [make-prerelease.sh command C]
  39
  40   4. Create the release branch using:
  41
  42         git tag -a binutils-2_30-branch   [e.g. for the 2.30 branch...]
  43         git push --tags origin binutils-2_30-branch
  44
  45   5. Update "BINUTILS_BRANCH" in gdbadmin's crontab:
  46
  47      Log in as gdbadmin on sourceware.org, and then:
  48
  49         $ cd crontab
  50         $ vi crontab
  51         [change BINUTILS_BRANCH]
  52         $ cvs ci crontab
  53         $ crontab crontab
  54
  55      If you do not have access to this account, please feel free to
  56      ask Joel Brobecker <brobecker AT adacore DOT com>.
  57
  58   6. Update bfd/configure and bfd/configure.ac on HEAD to indicate
  59      snapshot of the following release.
  60        [make-prerelease.sh command hv + C]
  61
  62   7. Rename the current HEAD version entry in Bugzilla, and create a
  63      new one.  E.g. rename "2.30 (HEAD)" to 2.30, and create "2.31
  64      (HEAD)":
  65
  66         https://sourceware.org/bugzilla/editversions.cgi?product=binutils
  67
  68   8. Update the release number in bfd/version.m4 for the mainline and
  69      the branch.  The mainline should have the minor number
  70      incremented, but the branch only needs the point value set to 90
  71      as the release has not actually happened yet.
  72
  73      Regenerate various files on both branch and HEAD by configuring
  74      with --enable-maintainer-mode.  NB/ Remember to build gold and
  75      gprof.  Commit the changes.  Make sure that this includes the
  76      .pot files as well as the configure and makefiles.
  77
  78   9. Create an initial prerelease:
  79
  80      a. Change the version on the branch (bfd/version.m4), regenerate
  81         the files, and check this in.
  82
  83      b. Create a source tarball of the branch sources:
  84
  85            ./src-release -x binutils
  86
  87      c. Build a test target using this tarball.
  88
  89      d. Upload the prerelease snapshot to the FTP:
  90
  91           scp ../binutils-$version.tar.xz sourceware.org:~ftp/pub/binutils/snapshots
  92           ssh sourceware.org md5sum ~ftp/pub/binutils/snapshots/binutils-$version.tar.xz
  93
  94   10. Send it to the Translation Project:
  95
  96         http://translationproject.org/html/maintainers.html
  97
  98       Sending mail for one of the POT files is sufficient.
  99
 100   11. Announce the availability of the snapshot and the branch on the
 101       binutils mailing list.  Set a date for when the release will
 102       actually happen.  Something like:
 103         ------------------------------------------------------------------------
 104         Hi Everyone,
 105
 106           The 2.XX branch has now been created:
 107
 108              git clone git://sourceware.org/git/binutils-gdb.git -b binutils-2_XX-branch 2.XX
 109
 110           A snapshot of the sources is also available here:
 111
 112             ftp://sourceware.org/pub/binutils/snapshots/binutils-2.XX.0.tar.xz
 113
 114           Please could all patches for the branch be run by me.
 115           The rules for the branch are:
 116
 117             * No new features.
 118             * Target specific bug fixes are OK.
 119             * Generic bug fixes are OK if they are important and widely tested.
 120             * Documentation updates/fixes are OK.
 121             * Translation updates are OK.
 122             * Fixes for testsuite failures are OK.
 123
 124           Ideally I would like to make the release happen in two weeks time,
 125           i.e. Saturday 27th Jan.  Which I hope will be enough time for everyone
 126           to get their final fixes in.
 127         ------------------------------------------------------------------------
 128
 129   12. Build various different toolchains, test them and nag
 130       maintainers to fix any testsuite failures for their
 131       architectures...
 132
 133
 134 When the time comes to actually make the release....
 135
 136
 137   20. Update the release number in bfd/version.m4 on the release
 138       branch to a whole new minor version number, without a point
 139       value.  Eg "2.29.90" becomes "2.30".  Change bfd/development.sh
 140       to set the value to "false".
 141
 142
 143 xxx -- fill in stuff here -- xxx
 144
 145
 146
 147
 148 -------------------------------------------------
 149 How to perform a point release.
 150 -------------------------------------------------
 151
 152 A point release is easier than a normal release since a lot of the
 153 work has already been done.  The branch has been created, the
 154 translations updated and the documentation uploaded.  So the procedure
 155 looks like this:
 156
 157   0. Decide that a point release is necessary.
 158
 159      Usually this only happens when a sufficient number of serious
 160      bugs have been found and fixed since the previous release, and a
 161      new official release is not imminent.
 162
 163   1. Tell the community that a point release is happening.  Ask
 164      maintainers to ensure that their ports are up to date on the
 165      release branch.  Ask the community if there are any bug fixes
 166      which are missing from the branch.  Allow some time for the
 167      responses to this step.
 168
 169   2. Make sure that the branch sources build, test and install
 170      correctly.
 171
 172   2.5 Prepare a list of the bugs which have been fixed.  This
 173       will be needed for step 8.
 174
 175   3. In the branch sources:
 176
 177        a. Update the minor release number in bfd/version.m4.
 178        b. Edit bfd/development.sh and set "development=false".
 179        c. Regenerate the configure files.
 180        d. Commit the updates along with a "this-is-the-2.XX.X-release"
 181           note in all of the changelogs.
 182        e. Tag the branch with the new release number:
 183
 184             git tag -a binutils-2_XX_X
 185               [optional: add "-u XXXXX" to sign with a gpg key]
 186             git push origin binutils-2_XX_X
 187
 188        f. Check that your file creation mask will create the
 189           correct file permissions.  Eg:
 190
 191             umask 022
 192
 193        g. Create the release tarballs:
 194             ./src-release -b -g -l -x binutils
 195
 196        h. Check that the files in the tarballs have the correct
 197           permissions.
 198
 199        i. Edit bfd/development.sh and set "development=true".
 200        j. Commit this change into the git repository.
 201        k. Clean up the source tree.  (Use "git status" to find new
 202            files, and remove them).
 203
 204      FIXME: The tarballs will contain spurious autom4te.cache
 205      directories which could be removed to reduce their size.
 206
 207   4. [If paranoid - upload the tarballs to one of the FTP servers and
 208       ask people to test it before going on to step 5].
 209
 210   5. Upload the tarballs to ftp.gnu.org.
 211
 212        gnupload --to ftp.gnu.org:binutils binutils-X.XX.X.tar.*
 213
 214      The gnupload script is in the gnulib/build-aux directory.
 215
 216   6. Upload the tarballs to sourceware.org:
 217
 218        sftp sourceware.org
 219          cd /ftp/pub/binutils/releases
 220          put binutils-X.XX.X.tar.*
 221          chmod 644 binutils-X.XX.X.tar.*
 222          quit
 223
 224     FIXME: Should the signatures (created by the gnupload script in
 225     step 5) be uploaded as well ?
 226
 227   7. Update web pages.  For sourceware.org:
 228
 229       * Log on to sourceware.org
 230       * Go /www/htdocs/binutils
 231       * Edit index.html
 232
 233       For the www.gnu.org site you have to email webmasters@gnu.org
 234       and ask them to make the change(s).
 235
 236   8. Send an emails to the binutils list, info-gnu@gnu.org and
 237      David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 238      (The email to Davis is so that he can update the GNU Toolchain
 239      social media).  Something like this:
 240 ------------------------------------------------------------------------
 241 Hi Everyone,
 242
 243   We are pleased to announce that version 2.XX.X of the Binutils project
 244   sources have been released and are now available for download at:
 245
 246     https://ftp.gnu.org/gnu/binutils
 247     https://sourceware.org/pub/binutils/releases/
 248
 249   This is a point release over the previous 2.XX version, containing bug
 250   fixes but no new features.
 251
 252   Our thanks go out to all of the binutils contributors, past and
 253   present, for helping to make this release possible.
 254
 255   Here is a list of the bugs that have been fixed:
 256     xx
 257     xx
 258     xx
 259     xx
 260 --------------------------------------------------------------------------
 261
 262 \f
 263 Copyright (C) 2017-2018 Free Software Foundation, Inc.
 264
 265 Copying and distribution of this file, with or without modification,
 266 are permitted in any medium without royalty provided the copyright
 267 notice and this notice are preserved.