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.37.90" becomes "2.38".  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.38-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.
 232
 233            tar tvf binutils-2.37.tar.bz2 | grep -e "---"
 234
 235       Also check that the man files are not empty.  (cf PR 28144).
 236
 237            tar tvf binutils-2.37.tar.xz | grep -e "\.1"
 238
 239   25. Sanity check the release on x86_64-pc-linux-gnu by building and
 240       running the testsuites (gas, gold, binutils and ld).  Make the
 241       source directory read-only before building.  Also test
 242       "make install".  If necessary fix any problems.
 243
 244         cd /dev/shm
 245         mkdir delme
 246         cd delme
 247         tar xvf <path-to-sources>/binutils-2.*.tar.lz
 248         chmod -R -w binutils-2.*
 249         mkdir build
 250         cd build
 251         ../binutils-2.X/configure --enable-gold --prefix=`pwd`/install --enable-plugins
 252         make all-gas all-gold all-ld all-binutils all-gprof
 253         make check-gas check-binutils check-ld check-gold
 254         make install-gas install-gold install-ld install-binutils
 255
 256         # Needed for step 29...
 257         make html pdf
 258
 259   26. Tag the branch with the new release number:
 260
 261             git tag -a binutils-2_3x     <=== Be careful to get the tag right
 262
 263               [optional: add "-u XXXXX" to sign with a gpg key]
 264               enter a tag message such as: "Official Binutils 2.3x release"
 265
 266             eg: git tag -a binutils-2_37 -u DD9E3C4F
 267
 268         NB/ If you do sign the binaries make sure to use a key
 269         that has been published with the FSF.
 270
 271         Then push the release:
 272
 273             git push origin binutils-2_3x
 274
 275         If you get an error message along the lines of "Invalid revision range ..." you can ignore it.
 276
 277   27. Upload the tarballs to ftp.gnu.org.
 278
 279        gnupload --to ftp.gnu.org:binutils binutils-2.3*.tar.*
 280
 281       Be prepared to provide the password for the key, if you signed the binaries.
 282
 283       The gnupload script is in the gnulib/build-aux directory.
 284
 285       Check for an email response from the upload.  If necessary
 286       fix any problems.
 287
 288   28. Upload the tarballs (and signatures) to sourceware.org:
 289
 290        sftp sourceware.org
 291          cd /sourceware/ftp/pub/binutils/releases
 292          put binutils-2.3*.tar.*
 293          chmod 644 binutils-2.3x.tar.*
 294          quit
 295
 296       FIXME: Are the signatures (created by the gnupload script in step 27) needed ?
 297       [The above commands upload them and nobody has complained, so suggest that they
 298       are retained].
 299
 300   29. Update web pages.  For sourceware.org:
 301
 302       Create a new documentation folder on the sourceware.org web
 303       pages as /sourceware/www/sourceware/htdocs/binutils/docs-2.3x.
 304
 305        sftp sourceware.org
 306          cd /sourceware/www/sourceware/htdocs/binutils
 307          mkdir docs-2.3x
 308          cd docs-2.3x
 309          mkdir as
 310          mkdir bfd
 311          mkdir binutils
 312          mkdir gprof
 313          mkdir ld
 314          cd ../docs-2.3(x-1)
 315          get index.html
 316
 317       Update the (local copy of the) index.html file to point to the
 318       new documentation and mention the new version and then upload it.
 319
 320          cd ../docs-2.3x
 321          put index.html
 322
 323       Make the html documentation locally with the "make html" command
 324       (see step 25 above).  Then upload and rename the directories as
 325       needed.  (sftp does not appear to support recursive uploads
 326       however, so the directories had to be made by hand, as shown above).
 327
 328          cd as
 329          lcd <build-dir>/gas/doc/as
 330          put *                {be patient - this takes a long time...}
 331          lcd ..
 332          cd ..
 333          put as.html
 334          put as.pdf
 335          cd ../bfd
 336          lcd ../../bfd/doc/bfd
 337          put *
 338          cd ..
 339          lcd ..
 340          put bfd.html
 341          put bfd.pdf
 342          cd ../binutils
 343          lcd ../../binutils/doc/binutils
 344          put *
 345          cd ..
 346          lcd ..
 347          put binutils.html
 348          put binutils.pdf
 349          cd ../gprof
 350          lcd ../../gprof/doc/gprof
 351          put *
 352          cd ..
 353          lcd ../..
 354          put gprof.html
 355          put gprof.pdf
 356          cd ../ld
 357          lcd ../ld/doc/ld
 358          put *
 359          cd ..
 360          lcd ../..
 361          put ld.html
 362          put ld.pdf
 363
 364       Edit the top level binutils index.html file to change the links
 365       to point to the new documentation.
 366
 367          cd ../..
 368          get index.html
 369          [edit]
 370          put index.html
 371          rm docs
 372          ln -s docs-2.3x docs
 373          quit
 374
 375       Check that the new web page is correct:
 376
 377           https://sourceware.org/binutils/
 378
 379       For the www.gnu.org site you have to email webmasters@gnu.org
 380       and ask them to make the change(s):
 381 ---------------------------------------
 382 Hi FSF Webmasters,
 383
 384   Please could the GNU Binutils webpage at:
 385
 386 https://www.gnu.org/software/binutils/binutils.html
 387
 388   be updated to indicate that there is now a newer version available
 389   (2.3x).  I have already updated the related page on the sourceware
 390   website so this might be useful as a template:
 391
 392 https://sourceware.org/binutils/
 393
 394   Thanks very much.
 395
 396 Cheers
 397 --------------------------------------
 398
 399   30. Send emails to binutils@sourceware.org, info-gnu@gnu.org and
 400       David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 401       Sign the email and include the checksum:
 402
 403           sha256sum binutils-2.3*.tar.*
 404
 405       (The email to Davis is so that he can update the GNU Toolchain
 406       social media).  Something like this:
 407       -----------------------------------------------------------------------
 408         Hi Everyone,
 409
 410         We are pleased to announce that version 2.3x of the GNU Binutils project
 411         sources have been released and are now available for download at:
 412
 413           https://ftp.gnu.org/gnu/binutils
 414           https://sourceware.org/pub/binutils/releases/
 415
 416           checksums: xxxx
 417
 418         This release contains numerous bug fixes, and also the
 419         following new features:
 420
 421           <extract info from the NEWS files>
 422
 423         Our thanks go out to all of the binutils contributors, past and
 424         present, for helping to make this release possible.
 425
 426       -----------------------------------------------------------------------
 427
 428   31. Clean up the source tree:
 429
 430         git clean -fdx .
 431
 432   32. Edit bfd/development.sh on the branch and set the development flag
 433       to "true".  (Leave the experimental flag set to "false").  Also bump
 434       the version in bfd/version.m4 by adding a trailing .0, so that the
 435       date suffix keeps the version lower than the trunk version.
 436       Regenerate files.  Commit these changes.
 437
 438   33. Email the binutils list telling everyone that the 2.3x branch
 439       is now open for business as usual and that patches no longer
 440       need special approval.
 441
 442   34. Examine the bfd/config.bfd file in the mainline sources and move
 443       any pending obsolete targets into the definitely obsolete
 444       section.  Create a changelog entry and commit.
 445
 446
 447
 448
 449 --------------------------------------------------------------------------
 450 How to perform a POINT release.
 451 --------------------------------------------------------------------------
 452
 453 A point release is easier than a normal release since a lot of the
 454 work has already been done.  The branch has been created, the
 455 translations updated and the documentation uploaded.  So the procedure
 456 looks like this:
 457
 458   0. Decide that a point release is necessary.
 459
 460      Usually this only happens when a sufficient number of serious
 461      bugs have been found and fixed since the previous release, and a
 462      new official release is not imminent.
 463
 464   1. Tell the community that a point release is happening.  Ask
 465      maintainers to ensure that their ports are up to date on the
 466      release branch.  Ask the community if there are any bug fixes
 467      which are missing from the branch.  Allow some time for the
 468      responses to this step.
 469
 470   2. Make sure that the branch sources build, test and install
 471      correctly.
 472
 473   2.5 Prepare a list of the bugs which have been fixed.  This
 474       will be needed for step 8.
 475
 476   3. In the branch sources:
 477
 478        a. Update the minor release number in bfd/version.m4.
 479        b. Edit bfd/development.sh, set "development=false".
 480        c. Regenerate the configure files.
 481        d. Remove spurious autom4te.cache files:
 482
 483           git clean -fdx
 484
 485        e. Commit the updates along with a "this-is-the-2.3x.y-release"
 486           note in all of the changelogs.
 487        f. Tag the branch with the new release number:
 488
 489             git tag -a binutils-2_3x_y
 490               [optional: add "-u XXXXX" to sign with a gpg key]
 491             git push origin binutils-2_3x_y
 492
 493        g. Check that your file creation mask will create the
 494           correct file permissions.  Ie:
 495
 496             umask 022
 497
 498        h. Create the release tarballs:
 499
 500             ./src-release -b -g -l -x binutils
 501
 502        i. Check that the files in the tarballs have the correct
 503           permissions.
 504
 505        j. Clean the source tree again
 506
 507             git clean -fdx
 508
 509        k. Edit bfd/development.sh and set "development=true".
 510        l. Commit this change.
 511
 512   4. [If paranoid - upload the tarballs to one of the FTP servers and
 513       ask people to test it before going on to step 5].
 514
 515   5. Upload the tarballs to ftp.gnu.org.
 516
 517        gnupload --to ftp.gnu.org:binutils binutils-*.tar.*
 518
 519      The gnupload script is in the gnulib/build-aux directory.
 520
 521   6. Upload the tarballs to sourceware.org:
 522
 523        sftp sourceware.org
 524          cd /sourceware/ftp/pub/binutils/releases
 525          put binutils-*.tar.*
 526          chmod 644 binutils-*.tar.*
 527          quit
 528
 529     It is OK to upload the signatures as well.
 530
 531   7. Update web pages.  For sourceware.org:
 532
 533       * Log on to sourceware.org
 534       * Go to /sourceware/www/sourceware/htdocs/binutils
 535       * Edit index.html and update the latest release number (if this is a latest release)
 536
 537       For the www.gnu.org site you have to email webmasters@gnu.org
 538       and ask them to make the change(s).
 539
 540   8. Send an emails to the binutils list, info-gnu@gnu.org and
 541      David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 542      (The email to Davis is so that he can update the GNU Toolchain
 543      social media).  Something like this:
 544
 545 ------------------------------------------------------------------------
 546 Hi Everyone,
 547
 548   We are pleased to announce that version 2.3x.y of the GNU Binutils
 549   project sources have been released and are now available for download at:
 550
 551     https://ftp.gnu.org/gnu/binutils
 552     https://sourceware.org/pub/binutils/releases/
 553
 554   This is a point release over the previous 2.3x version, containing bug
 555   fixes but no new features.
 556
 557   Our thanks go out to all of the binutils contributors, past and
 558   present, for helping to make this release possible.
 559
 560   Here is a list of the bugs that have been fixed:
 561     xx
 562     xx
 563     xx
 564     xx
 565 --------------------------------------------------------------------------
 566
 567   9. Create a new Bugzilla entry for the point release.
 568
 569        https://sourceware.org/bugzilla/editversions.cgi?product=binutils
 570
 571      And a new milestone too:
 572
 573        https://sourceware.org/bugzilla/editmilestones.cgi?product=binutils
 574 \f
 575 Copyright (C) 2017-2021 Free Software Foundation, Inc.
 576
 577 Copying and distribution of this file, with or without modification,
 578 are permitted in any medium without royalty provided the copyright
 579 notice and this notice are preserved.