1 README for MAKING BINUTILS RELEASES 2 3This is a collection of notes on how to perform a binutils release. A 4lot of this information can also be found in the maintain.texi file in 5the gnulib project: 6 7 https://www.gnu.org/software/gnulib/ 8 9It is useful to have a cloned copy of the sources of this project as 10it also contains an upload script used to install tarballs on the GNU 11FTP server. 12 13Make sure that you have upload authority on sourceware and fencepost. 14Beware - this is an involved process and can take weeks to complete. 15See the maintain.texi file for details on how to obtain these 16permissions. 17 18------------------------------------------------- 19How 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 133When 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------------------------------------------------- 245How to perform a point release. 246------------------------------------------------- 247 248A point release is easier than a normal release since a lot of the 249work has already been done. The branch has been created, the 250translations updated and the documentation uploaded. So the procedure 251looks 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------------------------------------------------------------------------ 337Hi 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 359Copyright (C) 2017-2018 Free Software Foundation, Inc. 360 361Copying and distribution of this file, with or without modification, 362are permitted in any medium without royalty provided the copyright 363notice and this notice are preserved. 364