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