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_33-branch
  43         git push origin binutils-2_33-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_33-branch 2.33
  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.33 (HEAD)" to 2.33, 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.33.51])
  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.32.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   8. 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-<version>.tar.xz /dev/shm
 114            cd /dev/shm
 115            tar xvf binutils-<version>.tar.xz
 116            mkdir build
 117            cd build
 118            ../<version>/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-<version>.tar.xz sourceware.org:~ftp/pub/binutils/snapshots
 127           ssh sourceware.org md5sum ~ftp/pub/binutils/snapshots/binutils-<version>.tar.xz
 128
 129      e. Clean up the source directory again.
 130
 131          git clean -fdx .
 132
 133    9. 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 2.3x release branch has been created for the FSF binutils.
 141
 142   A snapshot of the branch sources can be found here:
 143
 144     https://sourceware.org/pub/binutils/snapshots/binutils-2.3x.90.tar.xz
 145
 146   We hope to make the official release of the sources on the 8th July
 147   although that could change if there are important bugs that need to
 148   be fixed before the release.
 149 ------------------------------------------------------------------------
 150
 151   10. 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 2.3x branch has now been created:
 159
 160      git clone git://sourceware.org/git/binutils-gdb.git -b binutils-2_3x-branch 2.3x
 161
 162   A snapshot of the sources is also available here:
 163
 164     https://sourceware.org/pub/binutils/snapshots/binutils-2.3x.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. Saturday 27th Jan.  Which I hope will be enough time for everyone
 178   to get their final fixes in.
 179 ------------------------------------------------------------------------
 180
 181   11. Build various different toolchains, test them and nag
 182       maintainers to fix any testsuite failures for their
 183       architectures...
 184
 185
 186 When the time comes to actually make the release....
 187
 188
 189   20. Make sure that the branch sources still build, test and install
 190       correctly.  Make sure that the sources are clean, without any
 191       patch files (.reg .orig *~) left over.
 192
 193          cd <branch>
 194          git clean -dfx .
 195
 196   21. Update the release number in bfd/version.m4 on the release
 197       branch to a whole new minor version number, without a point
 198       value.  Eg "2.29.90" becomes "2.30".  Change bfd/development.sh
 199       to set all values to "false".  Regenerate the configure and
 200       makefiles.  And *info* files.  Add ChangeLog entries for the
 201       updates and add a  "this-is-the-2.3x-release" comment and
 202       commit.
 203
 204   22. Check that your file creation mask will create the
 205       correct file permissions.  Eg:
 206
 207             % umask
 208             22
 209
 210       Remove any spurious autom4te.cache files left over from the
 211       reconfiguring:
 212
 213             % find . -depth -name autom4te.cache -exec rm -r {} \;
 214
 215   23. Note - check to see if any new files have been added to the top
 216       level of the source directory, but which are not in the
 217       DEVO_SUPPORT variable in the src-release.sh script.  If they are
 218       needed then add them.
 219
 220        Create the release tarballs:
 221
 222             ./src-release.sh -b -g -l -x binutils
 223
 224   24. Check that the files in the tarballs have the correct
 225       permissions.
 226
 227   25. Sanity check the release on x86_64-pc-linux-gnu by building and
 228       running the testsuites (gas, gold, binutils and ld).  Make the
 229       source directory read-only before building.  Also test
 230       "make install".  If necessary fix any problems.
 231
 232   26. Tag the branch with the new release number:
 233
 234             git tag -a binutils-2_3x
 235               [optional: add "-u XXXXX" to sign with a gpg key]
 236             git push origin binutils-2_3x
 237
 238         NB/ If you do sign the binaries make sure to use a key
 239         that has been published with the FSF.
 240
 241   27. Upload the tarballs to ftp.gnu.org.
 242
 243        gnupload --to ftp.gnu.org:binutils binutils-2.3x.tar.*
 244
 245       The gnupload script is in the gnulib/build-aux directory.
 246
 247       Check for an email response from the upload.  If necessary
 248       fix any problems.
 249
 250   28. Upload the tarballs (and signatures) to sourceware.org:
 251
 252        sftp sourceware.org
 253          cd /sourceware/ftp/pub/binutils/releases
 254          put binutils-2.3x.tar.*
 255          chmod 644 binutils-2.3x.tar.*
 256          quit
 257
 258       FIXME: Should the signatures (created by the gnupload script in
 259       step 29) be uploaded as well ?
 260
 261   29. Update web pages.  For sourceware.org:
 262
 263       Create a new documentation folder on the sourceware.org web
 264       pages as /sourceware/www/sourceware/htdocs/binutils/docs-2.3x.
 265
 266        sftp sourceware.org
 267          cd /sourceware/www/sourceware/htdocs/binutils
 268          mkdir docs-2.3x
 269          cd docs-2.3x
 270          mkdir as bfd binutils gprof ld
 271          cd ../docs-2.3(x-1)
 272          get index.html
 273
 274       Update the (local copy of the) index.html file to point to the
 275       new documentation and mention the new version and then upload it.
 276
 277          cd ../docs-2.3x
 278          put index.html
 279
 280       Make the html documentation locally with the "make html" command
 281       and then upload and rename the directories as needed.  (sftp
 282       does not appear to support recursive uploads however, so the
 283       directories had to be made by hand, as shown above).
 284
 285          cd as
 286          lcd <build-dir>/gas/doc/as.html
 287          put *
 288          cd ../bfd
 289          lcd ../../../bfd/doc/bfd.html
 290          put *
 291          cd ../binutils
 292          lcd ../../../binutils/doc/binutils.html
 293          put *
 294          cd ../gprof
 295          lcd ../../../gprof/gprof.html
 296          put *
 297          cd ../ld
 298          lcd ../../ld/ld.html
 299          put *
 300
 301       Edit the top level binutils index.html file to change the links
 302       to the new documentation.
 303
 304          cd ../../..
 305          get index.html
 306          [edit]
 307          put index.html
 308          rm docs
 309          ln -s docs-2.3x docs
 310          quit
 311
 312       Check that the new web page is correct.
 313
 314       For the www.gnu.org site you have to email webmasters@gnu.org
 315       and ask them to make the change(s).
 316
 317   30. Send emails to binutils@sourceware.org, info-gnu@gnu.org and
 318       David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 319       Sign the email and include the checksum:
 320
 321           md5sum binutils-2.3x.tar.*
 322
 323       (The email to Davis is so that he can update the GNU Toolchain
 324       social media).  Something like this:
 325       -----------------------------------------------------------------------
 326         Hi Everyone,
 327
 328         We are pleased to announce that version 2.3x of the GNU Binutils project
 329         sources have been released and are now available for download at:
 330
 331           https://ftp.gnu.org/gnu/binutils
 332           https://sourceware.org/pub/binutils/releases/
 333
 334           checksums: xxxx
 335
 336        This release contains numerous bug fixes, and also the
 337        following new features:
 338
 339           <extract info from the NEWS files>
 340
 341        Our thanks go out to all of the binutils contributors, past and
 342        present, for helping to make this release possible.
 343
 344       -----------------------------------------------------------------------
 345
 346   31. Clean up the source tree:
 347
 348         git clean -fdx .
 349
 350   32. Edit bfd/development.sh on the branch and set the development flag
 351       to "true".  (Leave the experimental flag set to "false").  Also bump
 352       the version in bfd/version.m4 by adding a trailing .0, so that the
 353       date suffix keeps the version lower than the trunk version.
 354       Regenerate files.  Commit these changes.
 355
 356   33. Email the binutils list telling everyone that the 2.3x branch
 357       is now open for business as usual and that patched no longer
 358       need special approval.
 359
 360   34. Examine the bfd/config.bfd file and move any pending obsolete
 361       targets into the definitely obsolete section.  Create a
 362       changelog entry and commit.
 363
 364 -------------------------------------------------
 365 How to perform a point release.
 366 -------------------------------------------------
 367
 368 A point release is easier than a normal release since a lot of the
 369 work has already been done.  The branch has been created, the
 370 translations updated and the documentation uploaded.  So the procedure
 371 looks like this:
 372
 373   0. Decide that a point release is necessary.
 374
 375      Usually this only happens when a sufficient number of serious
 376      bugs have been found and fixed since the previous release, and a
 377      new official release is not imminent.
 378
 379   1. Tell the community that a point release is happening.  Ask
 380      maintainers to ensure that their ports are up to date on the
 381      release branch.  Ask the community if there are any bug fixes
 382      which are missing from the branch.  Allow some time for the
 383      responses to this step.
 384
 385   2. Make sure that the branch sources build, test and install
 386      correctly.
 387
 388   2.5 Prepare a list of the bugs which have been fixed.  This
 389       will be needed for step 8.
 390
 391   3. In the branch sources:
 392
 393        a. Update the minor release number in bfd/version.m4.
 394        b. Edit bfd/development.sh, set "development=false".
 395        c. Regenerate the configure files.
 396        c.1. Remove spurious autom4te.cache files:
 397
 398           find . -depth -name autom4te.cache -exec rm -r {} \;
 399
 400        d. Commit the updates along with a "this-is-the-2.3x.y-release"
 401           note in all of the changelogs.
 402        e. Tag the branch with the new release number:
 403
 404             git tag -a binutils-2_3x_y
 405               [optional: add "-u XXXXX" to sign with a gpg key]
 406             git push origin binutils-2_3x_y
 407
 408        f. Check that your file creation mask will create the
 409           correct file permissions.  Eg:
 410
 411             umask 022
 412
 413        g. Create the release tarballs:
 414
 415             ./src-release -b -g -l -x binutils
 416
 417        h. Check that the files in the tarballs have the correct
 418           permissions.
 419
 420        i. Edit bfd/development.sh and set "development=true".
 421        j. Commit this change into the git repository.
 422
 423   4. [If paranoid - upload the tarballs to one of the FTP servers and
 424       ask people to test it before going on to step 5].
 425
 426   5. Upload the tarballs to ftp.gnu.org.
 427
 428        gnupload --to ftp.gnu.org:binutils binutils-2.3x.y.tar.*
 429
 430      The gnupload script is in the gnulib/build-aux directory.
 431
 432   6. Upload the tarballs to sourceware.org:
 433
 434        sftp sourceware.org
 435          cd /sourceware/ftp/pub/binutils/releases
 436          put binutils-2.3x.y.tar.*
 437          chmod 644 binutils-2.3x.y.tar.*
 438          quit
 439
 440     It is OK to upload the signatures as well.
 441
 442   7. Update web pages.  For sourceware.org:
 443
 444       * Log on to sourceware.org
 445       * Go to /sourceware/www/sourceware/htdocs/binutils
 446       * Edit index.html
 447
 448       For the www.gnu.org site you have to email webmasters@gnu.org
 449       and ask them to make the change(s).
 450
 451   8. Send an emails to the binutils list, info-gnu@gnu.org and
 452      David Edelsohn <dje.gcc@gmail.com> announcing the new release.
 453      (The email to Davis is so that he can update the GNU Toolchain
 454      social media).  Something like this:
 455
 456 ------------------------------------------------------------------------
 457 Hi Everyone,
 458
 459   We are pleased to announce that version 2.3x.y of the GNU Binutils
 460   project sources have been released and are now available for download at:
 461
 462     https://ftp.gnu.org/gnu/binutils
 463     https://sourceware.org/pub/binutils/releases/
 464
 465   This is a point release over the previous 2.3x version, containing bug
 466   fixes but no new features.
 467
 468   Our thanks go out to all of the binutils contributors, past and
 469   present, for helping to make this release possible.
 470
 471   Here is a list of the bugs that have been fixed:
 472     xx
 473     xx
 474     xx
 475     xx
 476 --------------------------------------------------------------------------
 477   9. Clean up the source tree.
 478
 479             git clean -dfx .
 480
 481  10. Edit bfd/development.sh on the branch and set the development flag
 482      to "true".  Commit this change.
 483
 484 \f
 485 Copyright (C) 2017-2019 Free Software Foundation, Inc.
 486
 487 Copying and distribution of this file, with or without modification,
 488 are permitted in any medium without royalty provided the copyright
 489 notice and this notice are preserved.