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 configure files.
  28
  29   3. When branch day arrives add markers for the upcoming release to
  30      the NEWS files in gas, ld, and binutils.  No need to update NEWS
  31      in the gold directory - it has its own release numbering.
  32
  33      Likewise for the ChangeLog files in: bfd, binutils, config, cpu,
  34      elfcpp, gas, gold, gprof, include, ld, libctf, opcodes and toplevel.
  35
  36      Add a note of the name of the new branch to binutils/BRANCHES.
  37
  38      Commit these changes.
  39
  40   4. Create the release branch using:
  41
  42         git branch binutils-2_34-branch
  43         git push origin binutils-2_34-branch
  44
  45      If you get a message like:
  46
  47        remote: fatal: Invalid revision range 0000000000000000000000000000000000000000..f974f26cb16cc6fe3946f163c787a05e713fb77b
  48
  49      It appears that this can be ignored...
  50
  51   5. Make sure that the branch is there.  IE check out the branch sources:
  52
  53         git clone ssh://sourceware.org/git/binutils-gdb.git -b binutils-2_34-branch 2.34
  54
  55      If you get a message about being in a "detached head" state, something
  56      has gone wrong...
  57
  58      Keep the checked out sources - they are going to be needed in future
  59      steps.
  60
  61   6. Update "BINUTILS_BRANCH" in gdbadmin's crontab:
  62
  63      Log in as gdbadmin on sourceware.org, and then:
  64
  65         $ cd crontab
  66         $ vi crontab
  67         [change BINUTILS_BRANCH]
  68         $ cvs ci crontab
  69         $ crontab crontab
  70
  71      If you do not have access to this account, please feel free to
  72      ask Joel Brobecker <brobecker AT adacore DOT com>.
  73
  74   7. Rename the current HEAD version entry in Bugzilla, and create a
  75      new one.  E.g. rename "2.34 (HEAD)" to 2.34, and create "2.34
  76      (HEAD)":
  77
  78         https://sourceware.org/bugzilla/editversions.cgi?product=binutils
  79
  80   8. Update bfd/version.m4 on HEAD to indicate that is now a snapshot
  81      of the next release:
  82
  83        m4_define([BFD_VERSION], [2.34.50])
  84
  85      Update the release number in bfd/version.m4 for the BRANCH.
  86      The branch only needs the point value set to 90 as the release
  87      has not actually happened yet.
  88
  89        m4_define([BFD_VERSION], [2.33.90])
  90
  91      Regenerate various files on both branch and HEAD by configuring
  92      with "--enable-maintainer-mode --enable-gold" and then building
  93      with "make all-binutils all-gas all-gold all-gprof all-ld"
  94
  95      Add ChangeLog entries for the updated files.  Commit the changes.
  96      Make sure that this includes the .pot files as well as the
  97      configure and makefiles.
  98
  99   9. Create an initial pre-release:
 100
 101      a. Remove any auto-generated files, in order to force the
 102         src-release script to rebuild them.
 103
 104           cd <branch-sources>
 105           git clean -fdx .
 106
 107      b. Create a source tarball of the BRANCH sources:
 108
 109           ./src-release -x binutils
 110
 111      c. Build a test target using this tarball.
 112
 113            cp binutils-<OLD_VERSION>.90.tar.xz /dev/shm
 114            cd /dev/shm
 115            tar xvf binutils-<OLD_VERSION>.90.tar.xz
 116            mkdir build
 117            cd build
 118            ../binutils-<OLD_VERSION>.90/configure --quiet --enable-gold
 119            make
 120
 121         If there are problems, fix them.
 122
 123      d. Upload the pre-release snapshot to the sourceware FTP site:
 124
 125           cd <branch-sources>
 126           scp binutils-<OLD_VERSION>.90.tar.xz sourceware.org:~ftp/pub/binutils/snapshots
 127           ssh sourceware.org md5sum ~ftp/pub/binutils/snapshots/binutils-<OLD_VERSION>.90.tar.xz
 128
 129      e. Clean up the source directory again.
 130
 131          git clean -fdx .
 132
 133   10. Tell the Translation Project where to find the new tarball.
 134       <coordinator@translationproject.org>
 135       qv: http://translationproject.org/html/maintainers.html
 136
 137 ------------------------------------------------------------------------
 138 Dear Translation Project
 139
 140   The <NEW_VERSION> release branch has been created for the GNU binutils.
 141
 142   A snapshot of the branch sources can be found here:
 143
 144     https://sourceware.org/pub/binutils/snapshots/binutils-<OLD_VERSION>.90.tar.xz
 145
 146   We hope to make the official release of the sources on the <DATE>
 147   although that could change if there are important bugs that need to
 148   be fixed before the release.
 149 ------------------------------------------------------------------------
 150
 151   11. Announce the availability of the snapshot and the branch on the
 152       binutils mailing list.  Set a date for when the release will
 153       actually happen.  Something like:
 154
 155 ------------------------------------------------------------------------
 156 Hi Everyone,
 157
 158   The <NEW_VERSION> branch has now been created:
 159
 160      git clone git://sourceware.org/git/binutils-gdb.git -b binutils-<NEW_VERSION>-branch <NEW_VERSION>
 161
 162   A snapshot of the sources is also available here:
 163
 164     https://sourceware.org/pub/binutils/snapshots/binutils-<OLD_VERSION>.90.tar.xz
 165
 166   Please could all patches for the branch be run by me.
 167   The rules for the branch are:
 168
 169     * No new features.
 170     * Target specific bug fixes are OK.
 171     * Generic bug fixes are OK if they are important and widely tested.
 172     * Documentation updates/fixes are OK.
 173     * Translation updates are OK.
 174     * Fixes for testsuite failures are OK.
 175
 176   Ideally I would like to make the release happen in two weeks time,
 177   i.e. <DATE>.  Which I hope will be enough time for everyone
 178   to get their final fixes in.
 179 ------------------------------------------------------------------------
 180
 181   12. Build various different toolchains, test them and nag
 182       maintainers to fix any testsuite failures for their
 183       architectures...
 184
 185 ==============================================================================
 186
 187 When the time comes to actually make the release....
 188
 189
 190   20. Make sure that the branch sources still build, test and install
 191       correctly.  Make sure that the sources are clean, without any
 192       patch files (.reg .orig *~) left over.
 193
 194          cd <branch>
 195          git clean -dfx .
 196
 197   21. Update the release number in bfd/version.m4 on the release
 198       branch to a whole new minor version number, without a point
 199       value.  Eg "2.33.90" becomes "2.34".  Change bfd/development.sh
 200       to set all values to "false".  Regenerate the configure and
 201       makefiles.  And *info* files.  Add ChangeLog entries for the
 202       updates and add a  "this-is-the-2.3x-release" comment and
 203       commit.
 204
 205   22. Check that your file creation mask will create the
 206       correct file permissions.  Eg:
 207
 208             % umask
 209             22
 210
 211       Remove any spurious autom4te.cache files left over from the
 212       reconfiguring:
 213
 214             % find . -depth -name autom4te.cache -exec rm -r {} \;
 215
 216   23. Note - check to see if any new files have been added to the top
 217       level of the source directory, but which are not in the
 218       DEVO_SUPPORT variable in the src-release.sh script.  If they are
 219       needed then add them.
 220
 221        Create the release tarballs:
 222
 223             ./src-release.sh -b -g -l -x binutils
 224
 225   24. Check that the files in the tarballs have the correct
 226       permissions.
 227
 228   25. Sanity check the release on x86_64-pc-linux-gnu by building and
 229       running the testsuites (gas, gold, binutils and ld).  Make the
 230       source directory read-only before building.  Also test
 231       "make install".  If necessary fix any problems.
 232
 233   26. Tag the branch with the new release number:
 234
 235             git tag -a binutils-2_3x
 236               [optional: add "-u XXXXX" to sign with a gpg key]
 237             git push origin binutils-2_3x
 238
 239         NB/ If you do sign the binaries make sure to use a key
 240         that has been published with the FSF.
 241
 242   27. Upload the tarballs to ftp.gnu.org.
 243
 244        gnupload --to ftp.gnu.org:binutils binutils-2.3x.tar.*
 245
 246       The gnupload script is in the gnulib/build-aux directory.
 247
 248       Check for an email response from the upload.  If necessary
 249       fix any problems.
 250
 251   28. Upload the tarballs (and signatures) to sourceware.org:
 252
 253        sftp sourceware.org
 254          cd /sourceware/ftp/pub/binutils/releases
 255          put binutils-2.3x.tar.*
 256          chmod 644 binutils-2.3x.tar.*
 257          quit
 258
 259       FIXME: Should the signatures (created by the gnupload script in
 260       step 29) be uploaded as well ?
 261
 262   29. Update web pages.  For sourceware.org:
 263
 264       Create a new documentation folder on the sourceware.org web
 265       pages as /sourceware/www/sourceware/htdocs/binutils/docs-2.3x.
 266
 267        sftp sourceware.org
 268          cd /sourceware/www/sourceware/htdocs/binutils
 269          mkdir docs-2.3x
 270          cd docs-2.3x
 271          mkdir as bfd binutils gprof ld
 272          cd ../docs-2.3(x-1)
 273          get index.html
 274
 275       Update the (local copy of the) index.html file to point to the
 276       new documentation and mention the new version and then upload it.
 277
 278          cd ../docs-2.3x
 279          put index.html
 280
 281       Make the html documentation locally with the "make html" command
 282       and then upload and rename the directories as needed.  (sftp
 283       does not appear to support recursive uploads however, so the
 284       directories had to be made by hand, as shown above).
 285
 286          cd as
 287          lcd <build-dir>/gas/doc/as.html<
 288          put *
 289          cd ../bfd
 290          lcd ../../../bfd/doc/bfd.html
 291          put *
 292          cd ../binutils
 293          lcd ../../../binutils/doc/binutils.html
 294          put *
 295          cd ../gprof
 296          lcd ../../../gprof/gprof.html
 297          put *
 298          cd ../ld
 299          lcd ../../ld/ld.html
 300          put *
 301
 302       Edit the top level binutils index.html file to change the links
 303       to the new documentation.
 304
 305          cd ../../..
 306          get index.html
 307          [edit]
 308          put index.html
 309          rm docs
 310          ln -s docs-2.3x docs
 311          quit
 312
 313       Check that the new web page is correct.
 314
 315       For the www.gnu.org site you have to email webmasters@gnu.org
 316       and ask them to make the change(s).
 317
 318   30. Send emails to binutils@sourceware.org, info-gnu@gnu.org and
 319       David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 320       Sign the email and include the checksum:
 321
 322           md5sum binutils-2.3x.tar.*
 323
 324       (The email to Davis is so that he can update the GNU Toolchain
 325       social media).  Something like this:
 326       -----------------------------------------------------------------------
 327         Hi Everyone,
 328
 329         We are pleased to announce that version 2.3x of the GNU Binutils project
 330         sources have been released and are now available for download at:
 331
 332           https://ftp.gnu.org/gnu/binutils
 333           https://sourceware.org/pub/binutils/releases/
 334
 335           checksums: xxxx
 336
 337        This release contains numerous bug fixes, and also the
 338        following new features:
 339
 340           <extract info from the NEWS files>
 341
 342        Our thanks go out to all of the binutils contributors, past and
 343        present, for helping to make this release possible.
 344
 345       -----------------------------------------------------------------------
 346
 347   31. Clean up the source tree:
 348
 349         git clean -fdx .
 350
 351   32. Edit bfd/development.sh on the branch and set the development flag
 352       to "true".  (Leave the experimental flag set to "false").  Also bump
 353       the version in bfd/version.m4 by adding a trailing .0, so that the
 354       date suffix keeps the version lower than the trunk version.
 355       Regenerate files.  Commit these changes.
 356
 357   33. Email the binutils list telling everyone that the 2.3x branch
 358       is now open for business as usual and that patched no longer
 359       need special approval.
 360
 361   34. Examine the bfd/config.bfd file and move any pending obsolete
 362       targets into the definitely obsolete section.  Create a
 363       changelog entry and commit.
 364
 365 -------------------------------------------------
 366 How to perform a point release.
 367 -------------------------------------------------
 368
 369 A point release is easier than a normal release since a lot of the
 370 work has already been done.  The branch has been created, the
 371 translations updated and the documentation uploaded.  So the procedure
 372 looks like this:
 373
 374   0. Decide that a point release is necessary.
 375
 376      Usually this only happens when a sufficient number of serious
 377      bugs have been found and fixed since the previous release, and a
 378      new official release is not imminent.
 379
 380   1. Tell the community that a point release is happening.  Ask
 381      maintainers to ensure that their ports are up to date on the
 382      release branch.  Ask the community if there are any bug fixes
 383      which are missing from the branch.  Allow some time for the
 384      responses to this step.
 385
 386   2. Make sure that the branch sources build, test and install
 387      correctly.
 388
 389   2.5 Prepare a list of the bugs which have been fixed.  This
 390       will be needed for step 8.
 391
 392   3. In the branch sources:
 393
 394        a. Update the minor release number in bfd/version.m4.
 395        b. Edit bfd/development.sh, set "development=false".
 396        c. Regenerate the configure files.
 397        c.1. Remove spurious autom4te.cache files:
 398
 399           find . -depth -name autom4te.cache -exec rm -r {} \;
 400
 401        d. Commit the updates along with a "this-is-the-2.3x.y-release"
 402           note in all of the changelogs.
 403        e. Tag the branch with the new release number:
 404
 405             git tag -a binutils-2_3x_y
 406               [optional: add "-u XXXXX" to sign with a gpg key]
 407             git push origin binutils-2_3x_y
 408
 409        f. Check that your file creation mask will create the
 410           correct file permissions.  Eg:
 411
 412             umask 022
 413
 414        g. Create the release tarballs:
 415
 416             ./src-release -b -g -l -x binutils
 417
 418        h. Check that the files in the tarballs have the correct
 419           permissions.
 420
 421        i. Edit bfd/development.sh and set "development=true".
 422        j. Commit this change into the git repository.
 423
 424   4. [If paranoid - upload the tarballs to one of the FTP servers and
 425       ask people to test it before going on to step 5].
 426
 427   5. Upload the tarballs to ftp.gnu.org.
 428
 429        gnupload --to ftp.gnu.org:binutils binutils-2.3x.y.tar.*
 430
 431      The gnupload script is in the gnulib/build-aux directory.
 432
 433   6. Upload the tarballs to sourceware.org:
 434
 435        sftp sourceware.org
 436          cd /sourceware/ftp/pub/binutils/releases
 437          put binutils-2.3x.y.tar.*
 438          chmod 644 binutils-2.3x.y.tar.*
 439          quit
 440
 441     It is OK to upload the signatures as well.
 442
 443   7. Update web pages.  For sourceware.org:
 444
 445       * Log on to sourceware.org
 446       * Go to /sourceware/www/sourceware/htdocs/binutils
 447       * Edit index.html
 448
 449       For the www.gnu.org site you have to email webmasters@gnu.org
 450       and ask them to make the change(s).
 451
 452   8. Send an emails to the binutils list, info-gnu@gnu.org and
 453      David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 454      (The email to Davis is so that he can update the GNU Toolchain
 455      social media).  Something like this:
 456
 457 ------------------------------------------------------------------------
 458 Hi Everyone,
 459
 460   We are pleased to announce that version 2.3x.y of the GNU Binutils
 461   project sources have been released and are now available for download at:
 462
 463     https://ftp.gnu.org/gnu/binutils
 464     https://sourceware.org/pub/binutils/releases/
 465
 466   This is a point release over the previous 2.3x version, containing bug
 467   fixes but no new features.
 468
 469   Our thanks go out to all of the binutils contributors, past and
 470   present, for helping to make this release possible.
 471
 472   Here is a list of the bugs that have been fixed:
 473     xx
 474     xx
 475     xx
 476     xx
 477 --------------------------------------------------------------------------
 478   9. Clean up the source tree.
 479
 480             git clean -dfx .
 481
 482  10. Edit bfd/development.sh on the branch and set the development flag
 483      to "true".  Commit this change.
 484
 485 \f
 486 Copyright (C) 2017-2020 Free Software Foundation, Inc.
 487
 488 Copying and distribution of this file, with or without modification,
 489 are permitted in any medium without royalty provided the copyright
 490 notice and this notice are preserved.