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
 301          cd ../docs-2.3x
 302          put index.html
 303
 304       Make the html documentation locally with the "make html" command
 305       and then upload and rename the directories as needed.  (sftp
 306       does not appear to support recursive uploads however, so the
 307       directories had to be made by hand, as shown above).
 308
 309          cd as
 310          lcd <build-dir>/gas/doc/as.html
 311          put *      {be patient - this takes a long time...}
 312          cd ../bfd
 313          lcd ../../../bfd/doc/bfd.html
 314          put *
 315          cd ../binutils
 316          lcd ../../../binutils/doc/binutils.html
 317          put *
 318          cd ../gprof
 319          lcd ../../../gprof/gprof.html
 320          put *
 321          cd ../ld
 322          lcd ../../ld/ld.html
 323          put *
 324
 325       Edit the top level binutils index.html file to change the links
 326       to point to the new documentation.
 327
 328          cd ../../..
 329          get index.html
 330          [edit]
 331          put index.html
 332          rm docs
 333          ln -s docs-2.3x docs
 334          quit
 335
 336       Check that the new web page is correct.
 337
 338       For the www.gnu.org site you have to email webmasters@gnu.org
 339       and ask them to make the change(s).
 340
 341   30. Send emails to binutils@sourceware.org, info-gnu@gnu.org and
 342       David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 343       Sign the email and include the checksum:
 344
 345           md5sum binutils-2.3x.tar.*
 346
 347       (The email to Davis is so that he can update the GNU Toolchain
 348       social media).  Something like this:
 349       -----------------------------------------------------------------------
 350         Hi Everyone,
 351
 352         We are pleased to announce that version 2.3x of the GNU Binutils project
 353         sources have been released and are now available for download at:
 354
 355           https://ftp.gnu.org/gnu/binutils
 356           https://sourceware.org/pub/binutils/releases/
 357
 358           checksums: xxxx
 359
 360         This release contains numerous bug fixes, and also the
 361         following new features:
 362
 363           <extract info from the NEWS files>
 364
 365         Our thanks go out to all of the binutils contributors, past and
 366         present, for helping to make this release possible.
 367
 368       -----------------------------------------------------------------------
 369
 370   31. Clean up the source tree:
 371
 372         git clean -fdx .
 373
 374   32. Edit bfd/development.sh on the branch and set the development flag
 375       to "true".  (Leave the experimental flag set to "false").  Also bump
 376       the version in bfd/version.m4 by adding a trailing .0, so that the
 377       date suffix keeps the version lower than the trunk version.
 378       Regenerate files.  Commit these changes.
 379
 380   33. Email the binutils list telling everyone that the 2.3x branch
 381       is now open for business as usual and that patched no longer
 382       need special approval.
 383
 384   34. Examine the bfd/config.bfd file in the mainline sources and move
 385       any pending obsolete targets into the definitely obsolete
 386       section.  Create a changelog entry and commit.
 387
 388 --------------------------------------------------------------------------
 389 How to perform a point release.
 390 --------------------------------------------------------------------------
 391
 392 A point release is easier than a normal release since a lot of the
 393 work has already been done.  The branch has been created, the
 394 translations updated and the documentation uploaded.  So the procedure
 395 looks like this:
 396
 397   0. Decide that a point release is necessary.
 398
 399      Usually this only happens when a sufficient number of serious
 400      bugs have been found and fixed since the previous release, and a
 401      new official release is not imminent.
 402
 403   1. Tell the community that a point release is happening.  Ask
 404      maintainers to ensure that their ports are up to date on the
 405      release branch.  Ask the community if there are any bug fixes
 406      which are missing from the branch.  Allow some time for the
 407      responses to this step.
 408
 409   2. Make sure that the branch sources build, test and install
 410      correctly.
 411
 412   2.5 Prepare a list of the bugs which have been fixed.  This
 413       will be needed for step 8.
 414
 415   3. In the branch sources:
 416
 417        a. Update the minor release number in bfd/version.m4.
 418        b. Edit bfd/development.sh, set "development=false".
 419        c. Regenerate the configure files.
 420        c.1. Remove spurious autom4te.cache files:
 421
 422           find . -depth -name autom4te.cache -exec rm -r {} \;
 423
 424        d. Commit the updates along with a "this-is-the-2.3x.y-release"
 425           note in all of the changelogs.
 426        e. Tag the branch with the new release number:
 427
 428             git tag -a binutils-2_3x_y
 429               [optional: add "-u XXXXX" to sign with a gpg key]
 430             git push origin binutils-2_3x_y
 431
 432        f. Check that your file creation mask will create the
 433           correct file permissions.  Eg:
 434
 435             umask 022
 436
 437        g. Create the release tarballs:
 438
 439             ./src-release -b -g -l -x binutils
 440
 441        h. Check that the files in the tarballs have the correct
 442           permissions.
 443
 444        i. Edit bfd/development.sh and set "development=true".
 445        j. Commit this change into the git repository.
 446
 447   4. [If paranoid - upload the tarballs to one of the FTP servers and
 448       ask people to test it before going on to step 5].
 449
 450   5. Upload the tarballs to ftp.gnu.org.
 451
 452        gnupload --to ftp.gnu.org:binutils binutils-2.3x.y.tar.*
 453
 454      The gnupload script is in the gnulib/build-aux directory.
 455
 456   6. Upload the tarballs to sourceware.org:
 457
 458        sftp sourceware.org
 459          cd /sourceware/ftp/pub/binutils/releases
 460          put binutils-2.3x.y.tar.*
 461          chmod 644 binutils-2.3x.y.tar.*
 462          quit
 463
 464     It is OK to upload the signatures as well.
 465
 466   7. Update web pages.  For sourceware.org:
 467
 468       * Log on to sourceware.org
 469       * Go to /sourceware/www/sourceware/htdocs/binutils
 470       * Edit index.html
 471
 472       For the www.gnu.org site you have to email webmasters@gnu.org
 473       and ask them to make the change(s).
 474
 475   8. Send an emails to the binutils list, info-gnu@gnu.org and
 476      David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 477      (The email to Davis is so that he can update the GNU Toolchain
 478      social media).  Something like this:
 479
 480 ------------------------------------------------------------------------
 481 Hi Everyone,
 482
 483   We are pleased to announce that version 2.3x.y of the GNU Binutils
 484   project sources have been released and are now available for download at:
 485
 486     https://ftp.gnu.org/gnu/binutils
 487     https://sourceware.org/pub/binutils/releases/
 488
 489   This is a point release over the previous 2.3x version, containing bug
 490   fixes but no new features.
 491
 492   Our thanks go out to all of the binutils contributors, past and
 493   present, for helping to make this release possible.
 494
 495   Here is a list of the bugs that have been fixed:
 496     xx
 497     xx
 498     xx
 499     xx
 500 --------------------------------------------------------------------------
 501   9. Clean up the source tree.
 502
 503             git clean -dfx .
 504
 505  10. Edit bfd/development.sh on the branch and set the development flag
 506      to "true".  Commit this change.
 507
 508 \f
 509 Copyright (C) 2017-2020 Free Software Foundation, Inc.
 510
 511 Copying and distribution of this file, with or without modification,
 512 are permitted in any medium without royalty provided the copyright
 513 notice and this notice are preserved.