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