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