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      Likewise for all of the ChangeLog files.
  35      Add a note of the name of the new branch to binutils/BRANCHES.
  36      Commit these changes.
  37        [make-prerelease.sh command C]
  38
  39   4. Create the release branch using:
  40
  41         git tag -a binutils-2_31-branch   [e.g. for the 2.31 branch...]
  42           Suggested tag note: "The 2.31 branch for the FSF binutils"
  43
  44         git push --tags origin binutils-2_31-branch
  45
  46   5. Update "BINUTILS_BRANCH" in gdbadmin's crontab:
  47
  48      Log in as gdbadmin on sourceware.org, and then:
  49
  50         $ cd crontab
  51         $ vi crontab
  52         [change BINUTILS_BRANCH]
  53         $ cvs ci crontab
  54         $ crontab crontab
  55
  56      If you do not have access to this account, please feel free to
  57      ask Joel Brobecker <brobecker AT adacore DOT com>.
  58
  59   6. Rename the current HEAD version entry in Bugzilla, and create a
  60      new one.  E.g. rename "2.30 (HEAD)" to 2.30, and create "2.31
  61      (HEAD)":
  62
  63         https://sourceware.org/bugzilla/editversions.cgi?product=binutils
  64
  65   7. Check out the branch sources:
  66
  67       git clone ssh://sourceware.org/git/binutils-gdb.git -b binutils-2_31-branch 2.31
  68
  69   8. Update bfd/version.m4 on HEAD to indicate that is now a snapshot
  70      of the next release:
  71
  72        m4_define([BFD_VERSION], [2.31.51])
  73
  74      Update the release number in bfd/version.m4 for the the branch.
  75      The branch only needs the point value set to 90 as the release
  76      has not actually happened yet.
  77
  78        m4_define([BFD_VERSION], [2.30.90])
  79
  80      Regenerate various files on both branch and HEAD by configuring
  81      with --enable-maintainer-mode.  NB/ Remember to build gold and
  82      gprof.  Add ChangeLog entries.  Commit the changes.  Make sure
  83      that this includes the .pot files as well as the configure and
  84      makefiles.
  85
  86   8. Create an initial prerelease:
  87
  88      a. Create a source tarball of the branch sources:
  89
  90            ./src-release -x binutils
  91
  92      b. Build a test target using this tarball.
  93
  94      c. Upload the prerelease snapshot to the FTP:
  95
  96           scp ../binutils-$version.tar.xz sourceware.org:~ftp/pub/binutils/snapshots
  97           ssh sourceware.org md5sum ~ftp/pub/binutils/snapshots/binutils-$version.tar.xz
  98
  99    9. Send it to the Translation Project:
 100
 101         http://translationproject.org/html/maintainers.html
 102
 103       Sending mail for one of the POT files is sufficient.
 104
 105   10. Announce the availability of the snapshot and the branch on the
 106       binutils mailing list.  Set a date for when the release will
 107       actually happen.  Something like:
 108         ------------------------------------------------------------------------
 109         Hi Everyone,
 110
 111           The 2.XX branch has now been created:
 112
 113              git clone git://sourceware.org/git/binutils-gdb.git -b binutils-2_XX-branch 2.XX
 114
 115           A snapshot of the sources is also available here:
 116
 117             ftp://sourceware.org/pub/binutils/snapshots/binutils-2.XX.0.tar.xz
 118
 119           Please could all patches for the branch be run by me.
 120           The rules for the branch are:
 121
 122             * No new features.
 123             * Target specific bug fixes are OK.
 124             * Generic bug fixes are OK if they are important and widely tested.
 125             * Documentation updates/fixes are OK.
 126             * Translation updates are OK.
 127             * Fixes for testsuite failures are OK.
 128
 129           Ideally I would like to make the release happen in two weeks time,
 130           i.e. Saturday 27th Jan.  Which I hope will be enough time for everyone
 131           to get their final fixes in.
 132         ------------------------------------------------------------------------
 133
 134   12. Build various different toolchains, test them and nag
 135       maintainers to fix any testsuite failures for their
 136       architectures...
 137
 138
 139 When the time comes to actually make the release....
 140
 141
 142   20. Make sure that the branch sources still build, test and install
 143       correctly.
 144
 145   21. Update the release number in bfd/version.m4 on the release
 146       branch to a whole new minor version number, without a point
 147       value.  Eg "2.29.90" becomes "2.30".  Change bfd/development.sh
 148       to set the value to "false".  Regenerate the configure and
 149       makefiles.  Add changelog entries for the updates and add a
 150       "this-is-the-2.XX-release" commit and commit.  Make sure to
 151       include the .gmo files.
 152
 153   22. Check that your file creation mask will create the
 154       correct file permissions.  Eg:
 155
 156             umask 022
 157
 158   23. Create the release tarballs:
 159
 160             ./src-release -b -g -l -x binutils
 161
 162   24. Check that the files in the tarballs have the correct
 163       permissions.  FIXME: The tarballs will contain spurious
 164       autom4te.cache directories which could be removed to reduce
 165       their size.
 166
 167   25. Sanity check the release on x86_64-pc-linux-gnu by building and
 168       running the testsuite.  Make the source directory read-only
 169       before building.  Also test "make install".  If necessary fix
 170       any problems.
 171
 172   26. Tag the branch with the new release number:
 173
 174             git tag -a binutils-2_XX
 175               [optional: add "-u XXXXX" to sign with a gpg key]
 176             git push origin binutils-2_XX
 177
 178         NB/ If you do sign the binaries make sure to use a key
 179         that has been published with the FSF.
 180
 181   27. Clean up the source tree.  (Use "git status" to find new
 182       files, and remove them).
 183
 184   28. Edit bfd/development.sh on the branch and set
 185       "development=true".  Also bump the version by adding a trailing
 186       .0, so that the date suffix keeps the version lower than the
 187       trunk version.  Regenerate files.  Commit these changes.
 188
 189   29. Upload the tarballs to ftp.gnu.org.
 190
 191        gnupload --to ftp.gnu.org:binutils binutils-X.XX.tar.*
 192
 193       The gnupload script is in the gnulib/build-aux directory.
 194
 195       Check for an email response from the upload.  If necessary
 196       fix any problems.
 197
 198   30. Upload the tarballs (and signatures) to sourceware.org:
 199
 200        sftp sourceware.org
 201          cd /sourceware/ftp/pub/binutils/releases
 202          put binutils-X.XX.tar.*
 203          chmod 644 binutils-X.XX.tar.*
 204          quit
 205
 206       FIXME: Should the signatures (created by the gnupload script in
 207       step 29) be uploaded as well ?
 208
 209   31. Update web pages.  For sourceware.org:
 210
 211       Create a new documentation folder on the sourceware.org web
 212       pages as /sourceware/www/sourceware/htdocs/binutils/docs-X.XX.
 213       Make the html documentation locally with the "make html" command
 214       and then upload and rename the directories as needed.  Create an
 215       index.html file and then edit the docs link to point to the new
 216       docs-X.XX directory.
 217
 218       Update the sourceware.org site to point to the new documentation
 219       and  mention the new version.
 220
 221       For the www.gnu.org site you have to email webmasters@gnu.org
 222       and ask them to make the change(s).
 223
 224   32. Send emails to binutils@sourceware.org, info-gnu@gnu.org and
 225       David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 226       Sign the email and include the checksum.
 227       (The email to Davis is so that he can update the GNU Toolchain
 228       social media).  Something like this:
 229       ------------------------------------------------------------------------
 230         Hi Everyone,
 231
 232         We are pleased to announce that version 2.XX of the Binutils project
 233         sources have been released and are now available for download at:
 234
 235           https://ftp.gnu.org/gnu/binutils
 236           https://sourceware.org/pub/binutils/releases/
 237
 238           checksums: xxxx
 239
 240        This release contains numerous bug fixes, and also the
 241        following new features:
 242
 243           <extract info from the NEWS files>
 244
 245        Our thanks go out to all of the binutils contributors, past and
 246        present, for helping to make this release possible.
 247
 248       --------------------------------------------------------------------------
 249
 250 -------------------------------------------------
 251 How to perform a point release.
 252 -------------------------------------------------
 253
 254 A point release is easier than a normal release since a lot of the
 255 work has already been done.  The branch has been created, the
 256 translations updated and the documentation uploaded.  So the procedure
 257 looks like this:
 258
 259   0. Decide that a point release is necessary.
 260
 261      Usually this only happens when a sufficient number of serious
 262      bugs have been found and fixed since the previous release, and a
 263      new official release is not imminent.
 264
 265   1. Tell the community that a point release is happening.  Ask
 266      maintainers to ensure that their ports are up to date on the
 267      release branch.  Ask the community if there are any bug fixes
 268      which are missing from the branch.  Allow some time for the
 269      responses to this step.
 270
 271   2. Make sure that the branch sources build, test and install
 272      correctly.
 273
 274   2.5 Prepare a list of the bugs which have been fixed.  This
 275       will be needed for step 8.
 276
 277   3. In the branch sources:
 278
 279        a. Update the minor release number in bfd/version.m4.
 280        b. Edit bfd/development.sh and set "development=false".
 281        c. Regenerate the configure files.
 282        d. Commit the updates along with a "this-is-the-2.XX.X-release"
 283           note in all of the changelogs.
 284        e. Tag the branch with the new release number:
 285
 286             git tag -a binutils-2_XX_X
 287               [optional: add "-u XXXXX" to sign with a gpg key]
 288             git push origin binutils-2_XX_X
 289
 290        f. Check that your file creation mask will create the
 291           correct file permissions.  Eg:
 292
 293             umask 022
 294
 295        g. Create the release tarballs:
 296             ./src-release -b -g -l -x binutils
 297
 298        h. Check that the files in the tarballs have the correct
 299           permissions.
 300
 301        i. Edit bfd/development.sh and set "development=true".
 302        j. Commit this change into the git repository.
 303        k. Clean up the source tree.  (Use "git status" to find new
 304            files, and remove them).
 305
 306      FIXME: The tarballs will contain spurious autom4te.cache
 307      directories which could be removed to reduce their size.
 308
 309   4. [If paranoid - upload the tarballs to one of the FTP servers and
 310       ask people to test it before going on to step 5].
 311
 312   5. Upload the tarballs to ftp.gnu.org.
 313
 314        gnupload --to ftp.gnu.org:binutils binutils-X.XX.X.tar.*
 315
 316      The gnupload script is in the gnulib/build-aux directory.
 317
 318   6. Upload the tarballs to sourceware.org:
 319
 320        sftp sourceware.org
 321          cd /ftp/pub/binutils/releases
 322          put binutils-X.XX.X.tar.*
 323          chmod 644 binutils-X.XX.X.tar.*
 324          quit
 325
 326     FIXME: Should the signatures (created by the gnupload script in
 327     step 5) be uploaded as well ?
 328
 329   7. Update web pages.  For sourceware.org:
 330
 331       * Log on to sourceware.org
 332       * Go /www/htdocs/binutils
 333       * Edit index.html
 334
 335       For the www.gnu.org site you have to email webmasters@gnu.org
 336       and ask them to make the change(s).
 337
 338   8. Send an emails to the binutils list, info-gnu@gnu.org and
 339      David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 340      (The email to Davis is so that he can update the GNU Toolchain
 341      social media).  Something like this:
 342 ------------------------------------------------------------------------
 343 Hi Everyone,
 344
 345   We are pleased to announce that version 2.XX.X of the Binutils project
 346   sources have been released and are now available for download at:
 347
 348     https://ftp.gnu.org/gnu/binutils
 349     https://sourceware.org/pub/binutils/releases/
 350
 351   This is a point release over the previous 2.XX version, containing bug
 352   fixes but no new features.
 353
 354   Our thanks go out to all of the binutils contributors, past and
 355   present, for helping to make this release possible.
 356
 357   Here is a list of the bugs that have been fixed:
 358     xx
 359     xx
 360     xx
 361     xx
 362 --------------------------------------------------------------------------
 363
 364 \f
 365 Copyright (C) 2017-2018 Free Software Foundation, Inc.
 366
 367 Copying and distribution of this file, with or without modification,
 368 are permitted in any medium without royalty provided the copyright
 369 notice and this notice are preserved.