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