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      the NEWS files in gas, ld, and binutils.  No need to update NEWS
  31      in the gold directory - it has its own release numbering.
  32
  33      Likewise for the ChangeLog files in: bfd, binutils, config, cpu,
  34      elfcpp, gas, gold, gprof, include, ld, libctf, opcodes and toplevel.
  35
  36      Add a note of the name of the new branch to binutils/BRANCHES.
  37
  38      Commit these changes.
  39
  40   4. Create the release branch using:
  41
  42         git branch binutils-2_34-branch
  43         git push origin binutils-2_34-branch
  44
  45      If you get a message like:
  46
  47        remote: fatal: Invalid revision range 0000000000000000000000000000000000000000..f974f26cb16cc6fe3946f163c787a05e713fb77b
  48
  49      It appears that this can be ignored...
  50
  51   5. Make sure that the branch is there.  IE check out the branch sources:
  52
  53         git clone ssh://sourceware.org/git/binutils-gdb.git -b binutils-2_34-branch 2.34
  54
  55      If you get a message about being in a "detached head" state, something
  56      has gone wrong...
  57
  58      Keep the checked out sources - they are going to be needed in future
  59      steps.
  60
  61   6. Update "BINUTILS_BRANCH" in gdbadmin's crontab:
  62
  63      Log in as gdbadmin on sourceware.org, and then:
  64
  65         $ cd crontab
  66         $ vi crontab
  67         [change BINUTILS_BRANCH]
  68         $ cvs ci crontab
  69         $ crontab crontab
  70
  71      If you do not have access to this account, please feel free to
  72      ask Joel Brobecker <brobecker AT adacore DOT com>.
  73
  74   7. Rename the current HEAD version entry in Bugzilla, and create a
  75      new one.  E.g. rename "2.34 (HEAD)" to 2.34, and create "2.34
  76      (HEAD)":
  77
  78         https://sourceware.org/bugzilla/editversions.cgi?product=binutils
  79
  80   8. Update bfd/version.m4 on HEAD to indicate that is now a snapshot
  81      of the next release:
  82
  83        m4_define([BFD_VERSION], [2.34.50])
  84
  85      Update the release number in bfd/version.m4 for the BRANCH.
  86      The branch only needs the point value set to 90 as the release
  87      has not actually happened yet.
  88
  89        m4_define([BFD_VERSION], [2.33.90])
  90
  91      Regenerate various files on both branch and HEAD by configuring
  92      with "--enable-maintainer-mode --enable-gold" and then building
  93      with "make all-binutils all-gas all-gold all-gprof all-ld"
  94
  95      Add ChangeLog entries for the updated files.  Commit the changes.
  96      Make sure that this includes the .pot files as well as the
  97      configure and makefiles.
  98
  99   9. Create an initial pre-release:
 100
 101      a. Remove any auto-generated files, in order to force the
 102         src-release script to rebuild them.
 103
 104           cd <branch-sources>
 105           git clean -fdx .
 106
 107      b. Create a source tarball of the BRANCH sources:
 108
 109           ./src-release -x binutils
 110
 111      c. Build a test target using this tarball.
 112
 113            cp binutils-<OLD_VERSION>.90.tar.xz /dev/shm
 114            cd /dev/shm
 115            tar xvf binutils-<OLD_VERSION>.90.tar.xz
 116            mkdir build
 117            cd build
 118            ../binutils-<OLD_VERSION>.90/configure --quiet --enable-gold
 119            make
 120
 121         If there are problems, fix them.
 122
 123      d. Upload the pre-release snapshot to the sourceware FTP site:
 124
 125           cd <branch-sources>
 126           scp binutils-<OLD_VERSION>.90.tar.xz sourceware.org:~ftp/pub/binutils/snapshots
 127           ssh sourceware.org md5sum ~ftp/pub/binutils/snapshots/binutils-<OLD_VERSION>.90.tar.xz
 128
 129      e. Clean up the source directory again.
 130
 131          git clean -fdx .
 132
 133   10. Tell the Translation Project where to find the new tarball.
 134       <coordinator@translationproject.org>
 135       qv: http://translationproject.org/html/maintainers.html
 136
 137 ------------------------------------------------------------------------
 138 Dear Translation Project
 139
 140   The <NEW_VERSION> release branch has been created for the GNU binutils.
 141
 142   A snapshot of the branch sources can be found here:
 143
 144     https://sourceware.org/pub/binutils/snapshots/binutils-<OLD_VERSION>.90.tar.xz
 145
 146   We hope to make the official release of the sources on the <DATE>
 147   although that could change if there are important bugs that need to
 148   be fixed before the release.
 149 ------------------------------------------------------------------------
 150
 151   11. Announce the availability of the snapshot and the branch on the
 152       binutils mailing list.  Set a date for when the release will
 153       actually happen.  Something like:
 154
 155 ------------------------------------------------------------------------
 156 Hi Everyone,
 157
 158   The <NEW_VERSION> branch has now been created:
 159
 160      git clone git://sourceware.org/git/binutils-gdb.git -b binutils-<NEW_VERSION>-branch <NEW_VERSION>
 161
 162   A snapshot of the sources is also available here:
 163
 164     https://sourceware.org/pub/binutils/snapshots/binutils-<OLD_VERSION>.90.tar.xz
 165
 166   Please could all patches for the branch be run by me.
 167   The rules for the branch are:
 168
 169     * No new features.
 170     * Target specific bug fixes are OK.
 171     * Generic bug fixes are OK if they are important and widely tested.
 172     * Documentation updates/fixes are OK.
 173     * Translation updates are OK.
 174     * Fixes for testsuite failures are OK.
 175
 176   Ideally I would like to make the release happen in two weeks time,
 177   i.e. <DATE>.  Which I hope will be enough time for everyone
 178   to get their final fixes in.
 179 ------------------------------------------------------------------------
 180
 181   12. Build various different toolchains, test them and nag
 182       maintainers to fix any testsuite failures for their
 183       architectures...
 184
 185 ==============================================================================
 186
 187 When the time comes to actually make the release....
 188
 189
 190   20. Make sure that the branch sources still build, test and install
 191       correctly.  Make sure that the sources are clean, without any
 192       patch files (.reg .orig *~) left over.
 193
 194          cd <branch>
 195          git clean -dfx .
 196
 197   21. Update the release number in bfd/version.m4 on the release
 198       branch to a whole new minor version number, without a point
 199       value.  Eg "2.34.90" becomes "2.35".  Change bfd/development.sh
 200       to set all values to "false".  Regenerate the configure and
 201       makefiles.  And *info* files.  Add ChangeLog entries for the
 202       updates and add a  "this-is-the-2.3x-release" comment and
 203       commit.
 204
 205   22. Check that your file creation mask will create the
 206       correct file permissions.  Eg:
 207
 208             % umask
 209             22
 210
 211       Remove any spurious autom4te.cache files left over from the
 212       reconfiguring:
 213
 214             git clean -fdx
 215
 216   23. Note - check to see if any new files have been added to the top
 217       level of the source directory, but which are not in the
 218       DEVO_SUPPORT variable in the src-release.sh script.  If they are
 219       needed then add them.
 220
 221        Create the release tarballs:
 222
 223             ./src-release.sh -b -g -l -x binutils
 224
 225   24. Check that the files in the tarballs have the correct
 226       permissions.  (FIXME: How to do this ?)
 227
 228   25. Sanity check the release on x86_64-pc-linux-gnu by building and
 229       running the testsuites (gas, gold, binutils and ld).  Make the
 230       source directory read-only before building.  Also test
 231       "make install".  If necessary fix any problems.
 232
 233         cd /dev/shm
 234         mkdir delme
 235         cd delme
 236         tar xvf <path-to-sources>/binutils-2.X.tar.xz
 237         chmod -R -w binutils-2.X
 238         mkdir build
 239         cd build
 240         ../binutils-2.X/configure --enable-gold --prefix=`pwd`/install
 241         make all-gas all-gold all-ld all-binutils all-gprof
 242         make check-gas check-binutils check-ld check-gold
 243         make install-gas install-gold install-ld install-binutils
 244
 245   26. Tag the branch with the new release number:
 246
 247             git tag -a binutils-2_3x
 248               [optional: add "-u XXXXX" to sign with a gpg key]
 249               enter a tag message such as: "Official Binutils 2.3x release"
 250
 251         NB/ If you do sign the binaries make sure to use a key
 252         that has been published with the FSF.
 253
 254         Then push the release:
 255
 256             git push origin binutils-2_3x
 257
 258         If you get an error message along the lines of "Invalid revision range ..." you can ignore it.
 259
 260   27. Upload the tarballs to ftp.gnu.org.
 261
 262        gnupload --to ftp.gnu.org:binutils binutils-2.3x.tar.*
 263
 264       The gnupload script is in the gnulib/build-aux directory.
 265
 266       Check for an email response from the upload.  If necessary
 267       fix any problems.
 268
 269   28. Upload the tarballs (and signatures) to sourceware.org:
 270
 271        sftp sourceware.org
 272          cd /sourceware/ftp/pub/binutils/releases
 273          put binutils-2.3x.tar.*
 274          chmod 644 binutils-2.3x.tar.*
 275          quit
 276
 277       FIXME: Are the signatures (created by the gnupload script in step 27) needed ?
 278       [The above commands upload them and nobody has complained, so suggest that they
 279       are retained].
 280
 281   29. Update web pages.  For sourceware.org:
 282
 283       Create a new documentation folder on the sourceware.org web
 284       pages as /sourceware/www/sourceware/htdocs/binutils/docs-2.3x.
 285
 286        sftp sourceware.org
 287          cd /sourceware/www/sourceware/htdocs/binutils
 288          mkdir docs-2.3x
 289          cd docs-2.3x
 290          mkdir as
 291          mkdir bfd
 292          mkdir binutils
 293          mkdir gprof
 294          mkdir ld
 295          cd ../docs-2.3(x-1)
 296          get index.html
 297
 298       Update the (local copy of the) index.html file to point to the
 299       new documentation and mention the new version and then upload it.
 300       [NB/ FIXME: Special for updating from 2.34 documentation - restore
 301       the link to the GAS/NEWS which has been changed for 2.34 to a
 302       specific commit rather than the branch tag].
 303
 304          cd ../docs-2.3x
 305          put index.html
 306
 307       Make the html documentation locally with the "make html" command
 308       and then upload and rename the directories as needed.  (sftp
 309       does not appear to support recursive uploads however, so the
 310       directories had to be made by hand, as shown above).
 311
 312          cd as
 313          lcd <build-dir>/gas/doc/as.html
 314          put *      {be patient - this takes a long time...}
 315          cd ../bfd
 316          lcd ../../../bfd/doc/bfd.html
 317          put *
 318          cd ../binutils
 319          lcd ../../../binutils/doc/binutils.html
 320          put *
 321          cd ../gprof
 322          lcd ../../../gprof/gprof.html
 323          put *
 324          cd ../ld
 325          lcd ../../ld/ld.html
 326          put *
 327
 328       Edit the top level binutils index.html file to change the links
 329       to point to the new documentation.
 330
 331          cd ../../..
 332          get index.html
 333          [edit]
 334          put index.html
 335          rm docs
 336          ln -s docs-2.3x docs
 337          quit
 338
 339       Check that the new web page is correct.
 340
 341       For the www.gnu.org site you have to email webmasters@gnu.org
 342       and ask them to make the change(s).
 343
 344   30. Send emails to binutils@sourceware.org, info-gnu@gnu.org and
 345       David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 346       Sign the email and include the checksum:
 347
 348           md5sum binutils-2.3x.tar.*
 349
 350       (The email to Davis is so that he can update the GNU Toolchain
 351       social media).  Something like this:
 352       -----------------------------------------------------------------------
 353         Hi Everyone,
 354
 355         We are pleased to announce that version 2.3x of the GNU Binutils project
 356         sources have been released and are now available for download at:
 357
 358           https://ftp.gnu.org/gnu/binutils
 359           https://sourceware.org/pub/binutils/releases/
 360
 361           checksums: xxxx
 362
 363         This release contains numerous bug fixes, and also the
 364         following new features:
 365
 366           <extract info from the NEWS files>
 367
 368         Our thanks go out to all of the binutils contributors, past and
 369         present, for helping to make this release possible.
 370
 371       -----------------------------------------------------------------------
 372
 373   31. Clean up the source tree:
 374
 375         git clean -fdx .
 376
 377   32. Edit bfd/development.sh on the branch and set the development flag
 378       to "true".  (Leave the experimental flag set to "false").  Also bump
 379       the version in bfd/version.m4 by adding a trailing .0, so that the
 380       date suffix keeps the version lower than the trunk version.
 381       Regenerate files.  Commit these changes.
 382
 383   33. Email the binutils list telling everyone that the 2.3x branch
 384       is now open for business as usual and that patched no longer
 385       need special approval.
 386
 387   34. Examine the bfd/config.bfd file in the mainline sources and move
 388       any pending obsolete targets into the definitely obsolete
 389       section.  Create a changelog entry and commit.
 390
 391 --------------------------------------------------------------------------
 392 How to perform a point release.
 393 --------------------------------------------------------------------------
 394
 395 A point release is easier than a normal release since a lot of the
 396 work has already been done.  The branch has been created, the
 397 translations updated and the documentation uploaded.  So the procedure
 398 looks like this:
 399
 400   0. Decide that a point release is necessary.
 401
 402      Usually this only happens when a sufficient number of serious
 403      bugs have been found and fixed since the previous release, and a
 404      new official release is not imminent.
 405
 406   1. Tell the community that a point release is happening.  Ask
 407      maintainers to ensure that their ports are up to date on the
 408      release branch.  Ask the community if there are any bug fixes
 409      which are missing from the branch.  Allow some time for the
 410      responses to this step.
 411
 412   2. Make sure that the branch sources build, test and install
 413      correctly.
 414
 415   2.5 Prepare a list of the bugs which have been fixed.  This
 416       will be needed for step 8.
 417
 418   3. In the branch sources:
 419
 420        a. Update the minor release number in bfd/version.m4.
 421        b. Edit bfd/development.sh, set "development=false".
 422        c. Regenerate the configure files.
 423        c.1. Remove spurious autom4te.cache files:
 424
 425           find . -depth -name autom4te.cache -exec rm -r {} \;
 426
 427        d. Commit the updates along with a "this-is-the-2.3x.y-release"
 428           note in all of the changelogs.
 429        e. Tag the branch with the new release number:
 430
 431             git tag -a binutils-2_3x_y
 432               [optional: add "-u XXXXX" to sign with a gpg key]
 433             git push origin binutils-2_3x_y
 434
 435        f. Check that your file creation mask will create the
 436           correct file permissions.  Eg:
 437
 438             umask 022
 439
 440        g. Create the release tarballs:
 441
 442             ./src-release -b -g -l -x binutils
 443
 444        h. Check that the files in the tarballs have the correct
 445           permissions.
 446
 447        i. Edit bfd/development.sh and set "development=true".
 448        j. Commit this change into the git repository.
 449
 450   4. [If paranoid - upload the tarballs to one of the FTP servers and
 451       ask people to test it before going on to step 5].
 452
 453   5. Upload the tarballs to ftp.gnu.org.
 454
 455        gnupload --to ftp.gnu.org:binutils binutils-2.3x.y.tar.*
 456
 457      The gnupload script is in the gnulib/build-aux directory.
 458
 459   6. Upload the tarballs to sourceware.org:
 460
 461        sftp sourceware.org
 462          cd /sourceware/ftp/pub/binutils/releases
 463          put binutils-2.3x.y.tar.*
 464          chmod 644 binutils-2.3x.y.tar.*
 465          quit
 466
 467     It is OK to upload the signatures as well.
 468
 469   7. Update web pages.  For sourceware.org:
 470
 471       * Log on to sourceware.org
 472       * Go to /sourceware/www/sourceware/htdocs/binutils
 473       * Edit index.html
 474
 475       For the www.gnu.org site you have to email webmasters@gnu.org
 476       and ask them to make the change(s).
 477
 478   8. Send an emails to the binutils list, info-gnu@gnu.org and
 479      David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 480      (The email to Davis is so that he can update the GNU Toolchain
 481      social media).  Something like this:
 482
 483 ------------------------------------------------------------------------
 484 Hi Everyone,
 485
 486   We are pleased to announce that version 2.3x.y of the GNU Binutils
 487   project sources have been released and are now available for download at:
 488
 489     https://ftp.gnu.org/gnu/binutils
 490     https://sourceware.org/pub/binutils/releases/
 491
 492   This is a point release over the previous 2.3x version, containing bug
 493   fixes but no new features.
 494
 495   Our thanks go out to all of the binutils contributors, past and
 496   present, for helping to make this release possible.
 497
 498   Here is a list of the bugs that have been fixed:
 499     xx
 500     xx
 501     xx
 502     xx
 503 --------------------------------------------------------------------------
 504   9. Clean up the source tree.
 505
 506             git clean -dfx .
 507
 508  10. Edit bfd/development.sh on the branch and set the development flag
 509      to "true".  Commit this change.
 510
 511 \f
 512 Copyright (C) 2017-2020 Free Software Foundation, Inc.
 513
 514 Copying and distribution of this file, with or without modification,
 515 are permitted in any medium without royalty provided the copyright
 516 notice and this notice are preserved.