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