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