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