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. Regenerate various files on both branch and HEAD by configuring
  69      with --enable-maintainer-mode.  No need to check in changes to
  70      the autoconf/automake/etc files, but be sure the .pot files are
  71      up to date.  NB/ Remember to include gold and gprof.
  72
  73   9. Create an initial prerelease:
  74
  75      a. Change the version on the branch (bfd/version.m4), regenerate
  76         the files, and check this in.
  77
  78      b. Create a source tarball of the branch sources:
  79
  80            ./src-release -x binutils
  81
  82      c. Build a test target using this tarball.
  83
  84      d. Upload the prerelease snapshot to the FTP:
  85
  86           scp ../binutils-$version.tar.xz sourceware.org:~ftp/pub/binutils/snapshots
  87           ssh sourceware.org md5sum ~ftp/pub/binutils/snapshots/binutils-$version.tar.xz
  88
  89   10. Send it to the Translation Project:
  90
  91         http://translationproject.org/html/maintainers.html
  92
  93       Sending mail for one of the POT files is sufficient.
  94
  95   11. Announce the availability of the snapshot and the branch on the
  96       binutils mailing list.  Set a date for when the release will
  97       actually happen.  Something like:
  98 ------------------------------------------------------------------------
  99 Hi Everyone,
 100
 101   The 2.XX branch has now been created:
 102
 103      git clone git://sourceware.org/git/binutils-gdb.git -b binutils-2_XX-branch 2.XX
 104
 105   A snapshot of the sources is also available here:
 106
 107     ftp://sourceware.org/pub/binutils/snapshots/binutils-2.XX.0.tar.xz
 108
 109   Please could all patches for the branch be run by me.
 110   The rules for the branch are:
 111
 112     * No new features.
 113     * Target specific bug fixes are OK.
 114     * Generic bug fixes are OK if they are important and widely tested.
 115     * Documentation updates/fixes are OK.
 116     * Translation updates are OK.
 117     * Fixes for testsuite failures are OK.
 118
 119   Ideally I would like to make the release happen in two weeks time,
 120   i.e. Saturday 27th Jan.  Which I hope will be enough time for everyone
 121   to get their final fixes in.
 122 ------------------------------------------------------------------------
 123
 124   12. Build various different toolchains, test them and nag
 125       maintainers to fix any testsuite failures for their
 126       architectures...
 127
 128
 129 xxx -- fill in stuff here -- xxx
 130
 131 -------------------------------------------------
 132 How to perform a point release.
 133 -------------------------------------------------
 134
 135 A point release is easier than a normal release since a lot of the
 136 work has already been done.  The branch has been created, the
 137 translations updated and the documentation uploaded.  So the procedure
 138 looks like this:
 139
 140   0. Decide that a point release is necessary.
 141
 142      Usually this only happens when a sufficient number of serious
 143      bugs have been found and fixed since the previous release, and a
 144      new official release is not imminent.
 145
 146   1. Tell the community that a point release is happening.  Ask
 147      maintainers to ensure that their ports are up to date on the
 148      release branch.  Ask the community if there are any bug fixes
 149      which are missing from the branch.  Allow some time for the
 150      responses to this step.
 151
 152   2. Make sure that the branch sources build, test and install
 153      correctly.
 154
 155   2.5 Prepare a list of the bugs which have been fixed.  This
 156       will be needed for step 8.
 157
 158   3. In the branch sources:
 159
 160        a. Update the minor release number in bfd/version.m4.
 161        b. Edit bfd/development.sh and set "development=false".
 162        c. Regenerate the configure files.
 163        d. Commit the updates along with a "this-is-the-2.XX.X-release"
 164           note in all of the changelogs.
 165        e. Tag the branch with the new release number:
 166
 167             git tag -a binutils-2_XX_X
 168               [optional: add "-u XXXXX" to sign with a gpg key]
 169             git push origin binutils-2_XX_X
 170
 171        f. Check that your file creation mask will create the
 172           correct file permissions.  Eg:
 173
 174             umask 022
 175
 176        g. Create the release tarballs:
 177             ./src-release -b -g -l -x binutils
 178
 179        h. Check that the files in the tarballs have the correct
 180           permissions.
 181
 182        i. Edit bfd/development.sh and set "development=true".
 183        j. Commit this change into the git repository.
 184        k. Clean up the source tree.  (Use "git status" to find new
 185            files, and remove them).
 186
 187      FIXME: The tarballs will contain spurious autom4te.cache
 188      directories which could be removed to reduce their size.
 189
 190   4. [If paranoid - upload the tarballs to one of the FTP servers and
 191       ask people to test it before going on to step 5].
 192
 193   5. Upload the tarballs to ftp.gnu.org.
 194
 195        gnupload --to ftp.gnu.org:binutils binutils-X.XX.X.tar.*
 196
 197      The gnupload script is in the gnulib/build-aux directory.
 198
 199   6. Upload the tarballs to sourceware.org:
 200
 201        sftp sourceware.org
 202          cd /ftp/pub/binutils/releases
 203          put binutils-X.XX.X.tar.*
 204          chmod 644 binutils-X.XX.X.tar.*
 205          quit
 206
 207     FIXME: Should the signatures (created by the gnupload script in
 208     step 5) be uploaded as well ?
 209
 210   7. Update web pages.  For sourceware.org:
 211
 212       * Log on to sourceware.org
 213       * Go /www/htdocs/binutils
 214       * Edit index.html
 215
 216       For the www.gnu.org site you have to email webmasters@gnu.org
 217       and ask them to make the change(s).
 218
 219   8. Send an emails to the binutils list, info-gnu@gnu.org and
 220      David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 221      (The email to Davis is so that he can update the GNU Toolchain
 222      social media).  Something like this:
 223 ------------------------------------------------------------------------
 224 Hi Everyone,
 225
 226   We are pleased to announce that version 2.XX.X of the Binutils project
 227   sources have been released and are now available for download at:
 228
 229     https://ftp.gnu.org/gnu/binutils
 230     https://sourceware.org/pub/binutils/releases/
 231
 232   This is a point release over the previous 2.XX version, containing bug
 233   fixes but no new features.
 234
 235   Our thanks go out to all of the binutils contributors, past and
 236   present, for helping to make this release possible.
 237
 238   Here is a list of the bugs that have been fixed:
 239     xx
 240     xx
 241     xx
 242     xx
 243 --------------------------------------------------------------------------
 244
 245 \f
 246 Copyright (C) 2017-2018 Free Software Foundation, Inc.
 247
 248 Copying and distribution of this file, with or without modification,
 249 are permitted in any medium without royalty provided the copyright
 250 notice and this notice are preserved.