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