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
 412
 413 --------------------------------------------------------------------------
 414 How to perform a POINT release.
 415 --------------------------------------------------------------------------
 416
 417 A point release is easier than a normal release since a lot of the
 418 work has already been done.  The branch has been created, the
 419 translations updated and the documentation uploaded.  So the procedure
 420 looks like this:
 421
 422   0. Decide that a point release is necessary.
 423
 424      Usually this only happens when a sufficient number of serious
 425      bugs have been found and fixed since the previous release, and a
 426      new official release is not imminent.
 427
 428   1. Tell the community that a point release is happening.  Ask
 429      maintainers to ensure that their ports are up to date on the
 430      release branch.  Ask the community if there are any bug fixes
 431      which are missing from the branch.  Allow some time for the
 432      responses to this step.
 433
 434   2. Make sure that the branch sources build, test and install
 435      correctly.
 436
 437   2.5 Prepare a list of the bugs which have been fixed.  This
 438       will be needed for step 8.
 439
 440   3. In the branch sources:
 441
 442        a. Update the minor release number in bfd/version.m4.
 443        b. Edit bfd/development.sh, set "development=false".
 444        c. Regenerate the configure files.
 445        c.1. Remove spurious autom4te.cache files:
 446
 447           find . -depth -name autom4te.cache -exec rm -r {} \;
 448
 449        d. Commit the updates along with a "this-is-the-2.3x.y-release"
 450           note in all of the changelogs.
 451        e. Tag the branch with the new release number:
 452
 453             git tag -a binutils-2_3x_y
 454               [optional: add "-u XXXXX" to sign with a gpg key]
 455             git push origin binutils-2_3x_y
 456
 457        f. Check that your file creation mask will create the
 458           correct file permissions.  Eg:
 459
 460             umask 022
 461
 462        g. Create the release tarballs:
 463
 464             ./src-release -b -g -l -x binutils
 465
 466        h. Check that the files in the tarballs have the correct
 467           permissions.
 468
 469        i. Edit bfd/development.sh and set "development=true".
 470        j. Commit this change into the git repository.
 471
 472   4. [If paranoid - upload the tarballs to one of the FTP servers and
 473       ask people to test it before going on to step 5].
 474
 475   5. Upload the tarballs to ftp.gnu.org.
 476
 477        gnupload --to ftp.gnu.org:binutils binutils-2.3x.y.tar.*
 478
 479      The gnupload script is in the gnulib/build-aux directory.
 480
 481   6. Upload the tarballs to sourceware.org:
 482
 483        sftp sourceware.org
 484          cd /sourceware/ftp/pub/binutils/releases
 485          put binutils-2.3x.y.tar.*
 486          chmod 644 binutils-2.3x.y.tar.*
 487          quit
 488
 489     It is OK to upload the signatures as well.
 490
 491   7. Update web pages.  For sourceware.org:
 492
 493       * Log on to sourceware.org
 494       * Go to /sourceware/www/sourceware/htdocs/binutils
 495       * Edit index.html
 496
 497       For the www.gnu.org site you have to email webmasters@gnu.org
 498       and ask them to make the change(s).
 499
 500   8. Send an emails to the binutils list, info-gnu@gnu.org and
 501      David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 502      (The email to Davis is so that he can update the GNU Toolchain
 503      social media).  Something like this:
 504
 505 ------------------------------------------------------------------------
 506 Hi Everyone,
 507
 508   We are pleased to announce that version 2.3x.y of the GNU Binutils
 509   project sources have been released and are now available for download at:
 510
 511     https://ftp.gnu.org/gnu/binutils
 512     https://sourceware.org/pub/binutils/releases/
 513
 514   This is a point release over the previous 2.3x version, containing bug
 515   fixes but no new features.
 516
 517   Our thanks go out to all of the binutils contributors, past and
 518   present, for helping to make this release possible.
 519
 520   Here is a list of the bugs that have been fixed:
 521     xx
 522     xx
 523     xx
 524     xx
 525 --------------------------------------------------------------------------
 526
 527   9. Create a new Bugzilla entry for the point release.
 528
 529        https://sourceware.org/bugzilla/editversions.cgi?product=binutils
 530
 531      And a new milestone too:
 532
 533        https://sourceware.org/bugzilla/editmilestones.cgi?product=binutils
 534
 535  10. Clean up the source tree.
 536
 537             git clean -dfx .
 538
 539  11. Edit bfd/development.sh on the branch and set the development flag
 540      to "true".  Commit this change.
 541
 542 \f
 543 Copyright (C) 2017-2021 Free Software Foundation, Inc.
 544
 545 Copying and distribution of this file, with or without modification,
 546 are permitted in any medium without royalty provided the copyright
 547 notice and this notice are preserved.