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