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 all values to "false".  Regenerate the configure and
 168       makefiles.  And *info* files.  Add ChangeLog entries for the
 169       updates and add a  "this-is-the-2.XX-release" comment and
 170       commit.  Make sure to 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, set "development=false" and
 317        "experimental=false".
 318        c. Regenerate the configure files.
 319        c.1. Remove spurious autom4te.cache files:
 320
 321           find . -depth -name autom4te.cache -exec rm -r {} \;
 322
 323        d. Commit the updates along with a "this-is-the-2.XX.X-release"
 324           note in all of the changelogs.
 325        e. Tag the branch with the new release number:
 326
 327             git tag -a binutils-2_XX_X
 328               [optional: add "-u XXXXX" to sign with a gpg key]
 329             git push origin binutils-2_XX_X
 330
 331        f. Check that your file creation mask will create the
 332           correct file permissions.  Eg:
 333
 334             umask 022
 335
 336        g. Create the release tarballs:
 337             ./src-release -b -g -l -x binutils
 338
 339        h. Check that the files in the tarballs have the correct
 340           permissions.
 341
 342        i. Edit bfd/development.sh and set "development=true".
 343        j. Commit this change into the git repository.
 344        k. Clean up the source tree.  (Use "git status" to find new
 345            files, and remove them).
 346
 347   4. [If paranoid - upload the tarballs to one of the FTP servers and
 348       ask people to test it before going on to step 5].
 349
 350   5. Upload the tarballs to ftp.gnu.org.
 351
 352        gnupload --to ftp.gnu.org:binutils binutils-X.XX.X.tar.*
 353
 354      The gnupload script is in the gnulib/build-aux directory.
 355
 356   6. Upload the tarballs to sourceware.org:
 357
 358        sftp sourceware.org
 359          cd /sourceware/ftp/pub/binutils/releases
 360          put binutils-X.XX.X.tar.*
 361          chmod 644 binutils-X.XX.X.tar.*
 362          quit
 363
 364     It is OK to upload the signatures as well.
 365
 366   7. Update web pages.  For sourceware.org:
 367
 368       * Log on to sourceware.org
 369       * Go to /sourceware/www/sourceware/htdocs/binutils
 370       * Edit index.html
 371
 372       For the www.gnu.org site you have to email webmasters@gnu.org
 373       and ask them to make the change(s).
 374
 375   8. Send an emails to the binutils list, info-gnu@gnu.org and
 376      David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 377      (The email to Davis is so that he can update the GNU Toolchain
 378      social media).  Something like this:
 379 ------------------------------------------------------------------------
 380 Hi Everyone,
 381
 382   We are pleased to announce that version 2.XX.X of the GNU Binutils
 383   project sources have been released and are now available for download at:
 384
 385     https://ftp.gnu.org/gnu/binutils
 386     https://sourceware.org/pub/binutils/releases/
 387
 388   This is a point release over the previous 2.XX version, containing bug
 389   fixes but no new features.
 390
 391   Our thanks go out to all of the binutils contributors, past and
 392   present, for helping to make this release possible.
 393
 394   Here is a list of the bugs that have been fixed:
 395     xx
 396     xx
 397     xx
 398     xx
 399 --------------------------------------------------------------------------
 400
 401 \f
 402 Copyright (C) 2017-2018 Free Software Foundation, Inc.
 403
 404 Copying and distribution of this file, with or without modification,
 405 are permitted in any medium without royalty provided the copyright
 406 notice and this notice are preserved.