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. Create the release tarballs:
 184
 185             ./src-release.sh -b -g -l -x binutils
 186
 187   24. Check that the files in the tarballs have the correct
 188       permissions.
 189
 190   25. Sanity check the release on x86_64-pc-linux-gnu by building and
 191       running the testsuite.  Make the source directory read-only
 192       before building.  Also test "make install".  If necessary fix
 193       any problems.
 194
 195   26. Tag the branch with the new release number:
 196
 197             git tag -a binutils-2_XX
 198               [optional: add "-u XXXXX" to sign with a gpg key]
 199             git push origin binutils-2_XX
 200
 201         NB/ If you do sign the binaries make sure to use a key
 202         that has been published with the FSF.
 203
 204   27. Upload the tarballs to ftp.gnu.org.
 205
 206        gnupload --to ftp.gnu.org:binutils binutils-X.XX.tar.*
 207
 208       The gnupload script is in the gnulib/build-aux directory.
 209
 210       Check for an email response from the upload.  If necessary
 211       fix any problems.
 212
 213   28. Upload the tarballs (and signatures) to sourceware.org:
 214
 215        sftp sourceware.org
 216          cd /sourceware/ftp/pub/binutils/releases
 217          put binutils-X.XX.tar.*
 218          chmod 644 binutils-X.XX.tar.*
 219          quit
 220
 221       FIXME: Should the signatures (created by the gnupload script in
 222       step 29) be uploaded as well ?
 223
 224   29. Update web pages.  For sourceware.org:
 225
 226       Create a new documentation folder on the sourceware.org web
 227       pages as /sourceware/www/sourceware/htdocs/binutils/docs-X.XX.
 228       Make the html documentation locally with the "make html" command
 229       and then upload and rename the directories as needed.  Create an
 230       index.html file and then edit the docs link to point to the new
 231       docs-X.XX directory.
 232
 233       Update the index.html file in the directory containing the
 234       docs-X.XX entries to point to the new documentation and mention
 235       the new version.
 236
 237       For the www.gnu.org site you have to email webmasters@gnu.org
 238       and ask them to make the change(s).
 239
 240   30. Send emails to binutils@sourceware.org, info-gnu@gnu.org and
 241       David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 242       Sign the email and include the checksum.
 243       (The email to Davis is so that he can update the GNU Toolchain
 244       social media).  Something like this:
 245       ------------------------------------------------------------------------
 246         Hi Everyone,
 247
 248         We are pleased to announce that version 2.XX of the Binutils project
 249         sources have been released and are now available for download at:
 250
 251           https://ftp.gnu.org/gnu/binutils
 252           https://sourceware.org/pub/binutils/releases/
 253
 254           checksums: xxxx
 255
 256        This release contains numerous bug fixes, and also the
 257        following new features:
 258
 259           <extract info from the NEWS files>
 260
 261        Our thanks go out to all of the binutils contributors, past and
 262        present, for helping to make this release possible.
 263
 264       --------------------------------------------------------------------------
 265
 266   31. Clean up the source tree.  (Use "git status" to find new
 267       files, and remove them).
 268
 269   32. Edit bfd/development.sh on the branch and set
 270       "development=true".  Also bump the version in bfd/version.m4 by
 271       adding a trailing .0, so that the date suffix keeps the version
 272       lower than the trunk version.  Regenerate files.  Commit these
 273       changes.
 274
 275   33. Email the binutils list telling everyone that the 2.31 branch
 276       is now open for business as usual and that patched no longer
 277       need special approval.
 278
 279 -------------------------------------------------
 280 How to perform a point release.
 281 -------------------------------------------------
 282
 283 A point release is easier than a normal release since a lot of the
 284 work has already been done.  The branch has been created, the
 285 translations updated and the documentation uploaded.  So the procedure
 286 looks like this:
 287
 288   0. Decide that a point release is necessary.
 289
 290      Usually this only happens when a sufficient number of serious
 291      bugs have been found and fixed since the previous release, and a
 292      new official release is not imminent.
 293
 294   1. Tell the community that a point release is happening.  Ask
 295      maintainers to ensure that their ports are up to date on the
 296      release branch.  Ask the community if there are any bug fixes
 297      which are missing from the branch.  Allow some time for the
 298      responses to this step.
 299
 300   2. Make sure that the branch sources build, test and install
 301      correctly.
 302
 303   2.5 Prepare a list of the bugs which have been fixed.  This
 304       will be needed for step 8.
 305
 306   3. In the branch sources:
 307
 308        a. Update the minor release number in bfd/version.m4.
 309        b. Edit bfd/development.sh and set "development=false".
 310        c. Regenerate the configure files.
 311        d. Commit the updates along with a "this-is-the-2.XX.X-release"
 312           note in all of the changelogs.
 313        e. Tag the branch with the new release number:
 314
 315             git tag -a binutils-2_XX_X
 316               [optional: add "-u XXXXX" to sign with a gpg key]
 317             git push origin binutils-2_XX_X
 318
 319        f. Check that your file creation mask will create the
 320           correct file permissions.  Eg:
 321
 322             umask 022
 323
 324        g. Create the release tarballs:
 325             ./src-release -b -g -l -x binutils
 326
 327        h. Check that the files in the tarballs have the correct
 328           permissions.
 329
 330        i. Edit bfd/development.sh and set "development=true".
 331        j. Commit this change into the git repository.
 332        k. Clean up the source tree.  (Use "git status" to find new
 333            files, and remove them).
 334
 335      FIXME: The tarballs will contain spurious autom4te.cache
 336      directories which could be removed to reduce their size.
 337
 338   4. [If paranoid - upload the tarballs to one of the FTP servers and
 339       ask people to test it before going on to step 5].
 340
 341   5. Upload the tarballs to ftp.gnu.org.
 342
 343        gnupload --to ftp.gnu.org:binutils binutils-X.XX.X.tar.*
 344
 345      The gnupload script is in the gnulib/build-aux directory.
 346
 347   6. Upload the tarballs to sourceware.org:
 348
 349        sftp sourceware.org
 350          cd /ftp/pub/binutils/releases
 351          put binutils-X.XX.X.tar.*
 352          chmod 644 binutils-X.XX.X.tar.*
 353          quit
 354
 355     FIXME: Should the signatures (created by the gnupload script in
 356     step 5) be uploaded as well ?
 357
 358   7. Update web pages.  For sourceware.org:
 359
 360       * Log on to sourceware.org
 361       * Go /www/htdocs/binutils
 362       * Edit index.html
 363
 364       For the www.gnu.org site you have to email webmasters@gnu.org
 365       and ask them to make the change(s).
 366
 367   8. Send an emails to the binutils list, info-gnu@gnu.org and
 368      David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 369      (The email to Davis is so that he can update the GNU Toolchain
 370      social media).  Something like this:
 371 ------------------------------------------------------------------------
 372 Hi Everyone,
 373
 374   We are pleased to announce that version 2.XX.X of the Binutils project
 375   sources have been released and are now available for download at:
 376
 377     https://ftp.gnu.org/gnu/binutils
 378     https://sourceware.org/pub/binutils/releases/
 379
 380   This is a point release over the previous 2.XX version, containing bug
 381   fixes but no new features.
 382
 383   Our thanks go out to all of the binutils contributors, past and
 384   present, for helping to make this release possible.
 385
 386   Here is a list of the bugs that have been fixed:
 387     xx
 388     xx
 389     xx
 390     xx
 391 --------------------------------------------------------------------------
 392
 393 \f
 394 Copyright (C) 2017-2018 Free Software Foundation, Inc.
 395
 396 Copying and distribution of this file, with or without modification,
 397 are permitted in any medium without royalty provided the copyright
 398 notice and this notice are preserved.