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