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