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