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_36-branch
  43         git push origin binutils-2_36-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_36-branch 2.36
  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.36 (HEAD)" to 2.36, and create "2.37
  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.36.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.35.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 sha256sum ~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.35.90" becomes "2.36".  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 --enable-plugins
 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         # Needed for step 29...
 246         make html
 247
 248   26. Tag the branch with the new release number:
 249
 250             git tag -a binutils-2_3x
 251               [optional: add "-u XXXXX" to sign with a gpg key]
 252               enter a tag message such as: "Official Binutils 2.3x release"
 253
 254         NB/ If you do sign the binaries make sure to use a key
 255         that has been published with the FSF.
 256
 257         Then push the release:
 258
 259             git push origin binutils-2_3x
 260
 261         If you get an error message along the lines of "Invalid revision range ..." you can ignore it.
 262
 263   27. Upload the tarballs to ftp.gnu.org.
 264
 265        gnupload --to ftp.gnu.org:binutils binutils-2.3x.tar.*
 266
 267       The gnupload script is in the gnulib/build-aux directory.
 268
 269       Check for an email response from the upload.  If necessary
 270       fix any problems.
 271
 272   28. Upload the tarballs (and signatures) to sourceware.org:
 273
 274        sftp sourceware.org
 275          cd /sourceware/ftp/pub/binutils/releases
 276          put binutils-2.3x.tar.*
 277          chmod 644 binutils-2.3x.tar.*
 278          quit
 279
 280       FIXME: Are the signatures (created by the gnupload script in step 27) needed ?
 281       [The above commands upload them and nobody has complained, so suggest that they
 282       are retained].
 283
 284   29. Update web pages.  For sourceware.org:
 285
 286       Create a new documentation folder on the sourceware.org web
 287       pages as /sourceware/www/sourceware/htdocs/binutils/docs-2.3x.
 288
 289        sftp sourceware.org
 290          cd /sourceware/www/sourceware/htdocs/binutils
 291          mkdir docs-2.3x
 292          cd docs-2.3x
 293          mkdir as
 294          mkdir bfd
 295          mkdir binutils
 296          mkdir gprof
 297          mkdir ld
 298          cd ../docs-2.3(x-1)
 299          get index.html
 300
 301       Update the (local copy of the) index.html file to point to the
 302       new documentation and mention the new version and then upload it.
 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           https://sourceware.org/binutils/
 342
 343       For the www.gnu.org site you have to email webmasters@gnu.org
 344       and ask them to make the change(s):
 345 ---------------------------------------
 346 Hi FSF Webmasters,
 347
 348   Please could the GNU Binutils webpage at:
 349
 350 https://www.gnu.org/software/binutils/binutils.html
 351
 352   be updated to indicate that there is now a newer version available
 353   (2.3x).  I have already updated the related page on the sourceware
 354   website so this might be useful as a template:
 355
 356 https://sourceware.org/binutils/
 357
 358   Thanks very much.
 359
 360 Cheers
 361 --------------------------------------
 362
 363   30. Send emails to binutils@sourceware.org, info-gnu@gnu.org and
 364       David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 365       Sign the email and include the checksum:
 366
 367           sha256sum binutils-2.3x.tar.*
 368
 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.3x of the GNU 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           checksums: xxxx
 381
 382         This release contains numerous bug fixes, and also the
 383         following new features:
 384
 385           <extract info from the NEWS files>
 386
 387         Our thanks go out to all of the binutils contributors, past and
 388         present, for helping to make this release possible.
 389
 390       -----------------------------------------------------------------------
 391
 392   31. Clean up the source tree:
 393
 394         git clean -fdx .
 395
 396   32. Edit bfd/development.sh on the branch and set the development flag
 397       to "true".  (Leave the experimental flag set to "false").  Also bump
 398       the version in bfd/version.m4 by adding a trailing .0, so that the
 399       date suffix keeps the version lower than the trunk version.
 400       Regenerate files.  Commit these changes.
 401
 402   33. Email the binutils list telling everyone that the 2.3x branch
 403       is now open for business as usual and that patches no longer
 404       need special approval.
 405
 406   34. Examine the bfd/config.bfd file in the mainline sources and move
 407       any pending obsolete targets into the definitely obsolete
 408       section.  Create a changelog entry and commit.
 409
 410 --------------------------------------------------------------------------
 411 How to perform a point release.
 412 --------------------------------------------------------------------------
 413
 414 A point release is easier than a normal release since a lot of the
 415 work has already been done.  The branch has been created, the
 416 translations updated and the documentation uploaded.  So the procedure
 417 looks like this:
 418
 419   0. Decide that a point release is necessary.
 420
 421      Usually this only happens when a sufficient number of serious
 422      bugs have been found and fixed since the previous release, and a
 423      new official release is not imminent.
 424
 425   1. Tell the community that a point release is happening.  Ask
 426      maintainers to ensure that their ports are up to date on the
 427      release branch.  Ask the community if there are any bug fixes
 428      which are missing from the branch.  Allow some time for the
 429      responses to this step.
 430
 431   2. Make sure that the branch sources build, test and install
 432      correctly.
 433
 434   2.5 Prepare a list of the bugs which have been fixed.  This
 435       will be needed for step 8.
 436
 437   3. In the branch sources:
 438
 439        a. Update the minor release number in bfd/version.m4.
 440        b. Edit bfd/development.sh, set "development=false".
 441        c. Regenerate the configure files.
 442        c.1. Remove spurious autom4te.cache files:
 443
 444           find . -depth -name autom4te.cache -exec rm -r {} \;
 445
 446        d. Commit the updates along with a "this-is-the-2.3x.y-release"
 447           note in all of the changelogs.
 448        e. Tag the branch with the new release number:
 449
 450             git tag -a binutils-2_3x_y
 451               [optional: add "-u XXXXX" to sign with a gpg key]
 452             git push origin binutils-2_3x_y
 453
 454        f. Check that your file creation mask will create the
 455           correct file permissions.  Eg:
 456
 457             umask 022
 458
 459        g. Create the release tarballs:
 460
 461             ./src-release -b -g -l -x binutils
 462
 463        h. Check that the files in the tarballs have the correct
 464           permissions.
 465
 466        i. Edit bfd/development.sh and set "development=true".
 467        j. Commit this change into the git repository.
 468
 469   4. [If paranoid - upload the tarballs to one of the FTP servers and
 470       ask people to test it before going on to step 5].
 471
 472   5. Upload the tarballs to ftp.gnu.org.
 473
 474        gnupload --to ftp.gnu.org:binutils binutils-2.3x.y.tar.*
 475
 476      The gnupload script is in the gnulib/build-aux directory.
 477
 478   6. Upload the tarballs to sourceware.org:
 479
 480        sftp sourceware.org
 481          cd /sourceware/ftp/pub/binutils/releases
 482          put binutils-2.3x.y.tar.*
 483          chmod 644 binutils-2.3x.y.tar.*
 484          quit
 485
 486     It is OK to upload the signatures as well.
 487
 488   7. Update web pages.  For sourceware.org:
 489
 490       * Log on to sourceware.org
 491       * Go to /sourceware/www/sourceware/htdocs/binutils
 492       * Edit index.html
 493
 494       For the www.gnu.org site you have to email webmasters@gnu.org
 495       and ask them to make the change(s).
 496
 497   8. Send an emails to the binutils list, info-gnu@gnu.org and
 498      David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 499      (The email to Davis is so that he can update the GNU Toolchain
 500      social media).  Something like this:
 501
 502   9. Create a new Bugzilla entry for the point release.
 503
 504         https://sourceware.org/bugzilla/editversions.cgi?product=binutils
 505
 506 ------------------------------------------------------------------------
 507 Hi Everyone,
 508
 509   We are pleased to announce that version 2.3x.y of the GNU Binutils
 510   project sources have been released and are now available for download at:
 511
 512     https://ftp.gnu.org/gnu/binutils
 513     https://sourceware.org/pub/binutils/releases/
 514
 515   This is a point release over the previous 2.3x version, containing bug
 516   fixes but no new features.
 517
 518   Our thanks go out to all of the binutils contributors, past and
 519   present, for helping to make this release possible.
 520
 521   Here is a list of the bugs that have been fixed:
 522     xx
 523     xx
 524     xx
 525     xx
 526 --------------------------------------------------------------------------
 527   9. Clean up the source tree.
 528
 529             git clean -dfx .
 530
 531  10. Edit bfd/development.sh on the branch and set the development flag
 532      to "true".  Commit this change.
 533
 534 \f
 535 Copyright (C) 2017-2020 Free Software Foundation, Inc.
 536
 537 Copying and distribution of this file, with or without modification,
 538 are permitted in any medium without royalty provided the copyright
 539 notice and this notice are preserved.