binutils/README-how-to-make-a-release

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