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