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