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