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