README-how-to-make-a-release revision 1.1.1.4
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 Note - when performing a release it is helpful to edit this document 19 as you go, updating the example commands so that they are ready for 20 the release that follows. 21 22 ------------------------------------------------- 23 How to perform a release. 24 ------------------------------------------------- 25 26 1. Choose dates for the branch and release. Weekends are better 27 because they are less busy. It is typical to leave two weeks 28 between creating the branch and creating the release. 29 30 Send an email out warning contributors about the forthcoming 31 branch and release. 32 33 2. When the branch date is near: Update the libiberty and config 34 directories and the top level Makefile and configure files. Also 35 consider updating the toplevel libtool files. 36 37 ------------------------------------------------- 38 How to create the release branch. 39 ------------------------------------------------- 40 41 Approx time to complete from here: 2 hours ... 42 43 2.5 If you have not built from the sources recently then now is the 44 time to check that they still work... 45 46 3. When branch day arrives add markers for the upcoming release to 47 the NEWS files in gas, ld, and binutils. No need to update NEWS 48 in the gold directory - it has its own release numbering. 49 50 Likewise for the ChangeLog files in: bfd, binutils, cpu, 51 elfcpp, gas, gold, gprof, include, ld, libctf, opcodes and toplevel. 52 53 Add a note of the name of the new branch to binutils/BRANCHES. 54 55 Commit these changes. 56 57 4. Create the release branch using: 58 59 git branch binutils-2_42-branch 60 git push origin binutils-2_42-branch 61 62 If you get a message like: 63 64 remote: fatal: Invalid revision range 0000000000000000000000000000000000000000..f974f26cb16cc6fe3946f163c787a05e713fb77b 65 66 It appears that this can be ignored... 67 68 5. Make sure that the branch is there. IE check out the branch sources: 69 70 git clone ssh://sourceware.org/git/binutils-gdb.git -b binutils-2_42-branch 2.42 71 72 If you get a message about being in a "detached head" state, something 73 has gone wrong... 74 75 Keep the checked out sources - they are going to be needed in future 76 steps. 77 78 6. Update "BINUTILS_BRANCH" in gdbadmin's crontab: 79 80 Log in as gdbadmin on sourceware.org, and then: 81 82 $ cd crontab 83 $ vi crontab 84 [change BINUTILS_BRANCH] 85 $ cvs ci crontab 86 $ crontab crontab 87 88 If you do not have access to this account, please feel free to 89 ask Joel Brobecker <brobecker AT adacore DOT com>. 90 91 7. Rename the current HEAD version entry in Bugzilla, and create a 92 new one. E.g. rename "2.42 (HEAD)" to 2.42, and create 93 "2.43 (HEAD)": 94 95 https://sourceware.org/bugzilla/editversions.cgi?product=binutils 96 97 8. Update bfd/version.m4 on HEAD to indicate that is now a snapshot 98 of the next release and the BRANCH to indicate that it is almost 99 ready for the release. 100 101 So if the release is going to be 2.42 then the version number on 102 the BRANCH should be set to 2.41.90 - ie almost, but not quite 2.42, 103 and the version number on the MAINLINE should be set to 2.42.50 - 104 ie half way to 2.43 release. 105 106 So the BRANCH bfd/version.m4 has: 107 108 m4_define([BFD_VERSION], [2.41.90]) 109 110 and the MAINLINE has: 111 112 m4_define([BFD_VERSION], [2.42.50]) 113 114 Regenerate various files on both branch and HEAD by configuring 115 with "--enable-maintainer-mode --enable-gold --enable-shared" and then building 116 with "make all-binutils all-gas all-gold all-gprof all-gprofng all-ld" 117 118 Add ChangeLog entries for the updated files. Commit the changes. 119 Make sure that this includes the .pot files as well as the 120 configure and makefiles. 121 122 9. Create an initial pre-release: 123 124 a. Remove any auto-generated files, in order to force the 125 src-release script to rebuild them. 126 127 cd <branch-sources> 128 git clean -fdx 129 130 b. Create a source tarball of the BRANCH sources: 131 132 ./src-release.sh -x binutils 133 134 FIXME: Not sure if the following steps are needed... 135 136 Add a .dirstamp file to the gas/doc subdirectory: 137 138 touch -d <today's date> binutils-2.<release>/gas/doc/.dirstamp 139 tar rvf binutils-<release>.tar binutils-<release>/gas/doc/.ditstamp 140 rm binutils-<release>.tar.xz 141 xz -9 binutils-<release>.tar 142 143 eg: 144 touch -d 2024-01-01 binutils-2.41.90/gas/doc/.dirstamp 145 tar rvf binutils-2.41.90.tar binutils-2.41.90/gas/doc/.dirstamp 146 rm binutils-2.41.90.tar.xz 147 xz -9 binutils-2.41.90.tar 148 149 ...END OF FIXME 150 151 c. Build a test target using this tarball. 152 153 cp binutils-2.41.90.tar.xz /dev/shm 154 pushd /dev/shm 155 tar xvf binutils-2.41.90.tar.xz 156 mkdir build 157 cd build 158 ../binutils-2.41.90/configure --quiet --enable-gold 159 make 160 popd 161 162 If there are problems, fix them. 163 164 d. Upload the pre-release snapshot to the sourceware FTP site: 165 166 scp binutils-2.40.90.tar.xz sourceware.org:/var/ftp/pub/binutils/snapshots 167 ssh sourceware.org sha256sum ~ftp/pub/binutils/snapshots/binutils-2.40.90.tar.xz 168 169 e. Clean up the source directory again. 170 171 git clean -fdx 172 173 10. Tell the Translation Project where to find the new tarball. 174 <coordinator (a] translationproject.org> 175 qv: https://translationproject.org/html/maintainers.html 176 177 ------------------------------------------------------------------------ 178 Dear Translation Project 179 180 The 2.42 release branch has been created for the GNU Binutils project. 181 182 A snapshot of the branch sources can be found here: 183 184 https://sourceware.org/pub/binutils/snapshots/binutils-2.41.90.tar.xz 185 186 We hope to make the official release of the sources on the <DATE> 187 although that could change if there are important bugs that need to 188 be fixed before the release. 189 ------------------------------------------------------------------------ 190 191 11. Announce the availability of the snapshot and the branch on the 192 binutils mailing list. Set a date for when the release will 193 actually happen. Something like: 194 195 196 Hi Everyone, 197 198 The <NEW_VERSION> branch has now been created: 199 200 git clone git://sourceware.org/git/binutils-gdb.git -b binutils-<NEW_VERSION>-branch 201 202 A snapshot of the sources is also available here: 203 204 https://sourceware.org/pub/binutils/snapshots/binutils-<OLD_VERSION>.90.tar.xz 205 206 Please could all patches for the branch be run by me. 207 The rules for the branch are: 208 209 * No new features. 210 * Target specific bug fixes are OK. 211 * Generic bug fixes are OK if they are important and widely tested. 212 * Documentation updates/fixes are OK. 213 * Translation updates are OK. 214 * Fixes for testsuite failures are OK. 215 216 Ideally I would like to make the release happen in two weeks time, 217 i.e. <DATE>. Which I hope will be enough time for everyone 218 to get their final fixes in. 219 ------------------------------------------------------------------------ 220 221 12. Build various different toolchains, test them and nag 222 maintainers to fix any testsuite failures for their 223 architectures... 224 225 ============================================================================== 226 ============================================================================== 227 228 For the next few weeks, monitor the mailing list for new translations 229 and respond to any requests to have patches applied to the branch. 230 231 ============================================================================== 232 ============================================================================== 233 234 Then, a couple of weeks later ... 235 236 ------------------------------------------------- 237 How to create the release. 238 ------------------------------------------------- 239 240 20. Make sure that the branch sources still build, test and install 241 correctly. Make sure that the sources are clean, without any 242 patch files (.reg .orig *~) left over. 243 244 cd <branch> 245 git pull 246 git clean -fdx 247 cd <builds> 248 make 249 250 21. a. Update the release number in bfd/version.m4 on the release 251 branch to a whole new minor version number, without a point 252 value. Eg "2.41.90" becomes "2.42". NB/ Not: "2.42.00" 253 254 b. Change bfd/development.sh to set all values to "false". 255 256 c. Regenerate the configure and makefiles. And *info* files. 257 258 cd <build-configured-with-enable-maintainer-mode> 259 make all-gas all-ld all-binutils all-gprof all-gold all-gprofng all-libctf 260 make info 261 262 d. Create a ChangeLog from the git refs for all of the commits 263 from when changelog entries were no longer required: 264 265 gitlog-to-changelog --since=2021-07-03 > ChangeLog.git 266 git add ChangeLog.git 267 268 The gitlog-to-changelog script is part of the sources 269 of the "config" project. 270 271 Add an entry for ChangeLog.git to the src-release.sh script's 272 DEVO_SUPPORT list, so that it is included in the release. 273 274 FIXME: it would be better if the ChangeLog.git file was permanently 275 added to the src-release.sh script, but this mean that it would have 276 to exist in the master repository, and that the GDB project would 277 need to agree to have it there. 278 279 e. Add ChangeLog entries for all of the updates and add a 280 "this-is-the-2.42-release" comment and commit. 281 282 git add . 283 git commit 284 git push 285 286 22. Check that your file creation mask will create the 287 correct file permissions. Eg: 288 289 % umask 290 22 291 292 Remove any spurious autom4te.cache files left over from the 293 reconfiguring: 294 295 git clean -fdx 296 297 23. Note - check to see if any new files have been added to the top 298 level of the source directory, but which are not in the 299 DEVO_SUPPORT variable in the src-release.sh script. If they are 300 needed then add them. 301 302 PARANOIA: Check that there are no pending commits: 303 304 git status 305 306 Then create the release tarballs: 307 308 ./src-release.sh -b -g -l -x binutils 309 310 OR ... for a more reproducible tarball: 311 312 ./src-release.sh -b -g -l -x -r `git log -1 --format=%cd --date=format:%F bfd/version.m4` binutils 313 314 24. Check that the files in the tarballs have the correct 315 permissions. 316 317 tar tvf binutils-*.tar.xz | grep -e "---" 318 319 Also check that the man files are not empty. (cf PR 28144). 320 321 tar tvf binutils-*.tar.xz | grep -e "\.1" 322 323 25. Sanity check the release on x86_64-pc-linux-gnu by building and 324 running the testsuites (gas, gold, binutils and ld). 325 Make the source directory read-only before building. 326 Also test 'make install'. 327 Also build the html and pdf documentation files. 328 If necessary fix any problems. 329 330 pushd /dev/shm 331 mkdir delme 332 cd delme 333 tar xvf <path-to-sources>/binutils-2.*.tar.lz 334 chmod -R -w binutils-2.* 335 mkdir build 336 cd build 337 ../binutils-2.*/configure --quiet --enable-gold --prefix=`pwd`/install --enable-plugins --enable-shared 338 make all-gas all-gold all-ld all-binutils all-gprof all-gprofng 339 make check-gas check-binutils check-ld check-gold 340 make install-gas install-gold install-ld install-binutils install-gprofng 341 342 # Needed for step 29... 343 make html pdf html-libctf pdf-libctf html-libsframe pdf-libsframe 344 345 popd 346 347 26. Tag the branch with the new release number: 348 [optional: add "-u XXXXX" to sign with a gpg key] 349 enter a tag message such as: "Official GNU Binutils 2.4x release" 350 351 git tag -a <TAG> -u <Your Key> 352 git tag -a binutils-2_42 -u DD9E3C4F <=== Be careful to get the tag right 353 354 NB/ If you do sign the binaries make sure to use a key 355 that has been published with the FSF. 356 357 Then push the release: 358 359 git push origin binutils-2_42 360 361 If you get an error message along the lines of: 362 "Invalid revision range ..." 363 you can ignore it. 364 365 27. Upload the tarballs to ftp.gnu.org. 366 367 gnupload --to ftp.gnu.org:binutils binutils-2.42.tar.* 368 369 Be prepared to provide the password for the key, if you 370 signed the binaries. 371 372 The gnupload script is in the gnulib/build-aux directory. 373 It uses the ncftp package for transmitting the files. 374 375 Check for an email response from the upload. If necessary 376 fix any problems. (The response might take a while, so 377 proceed with the next steps if you are confident that 378 everything is OK). 379 380 28. Upload the tarballs (and signatures) to sourceware.org: 381 382 sftp sourceware.org 383 cd /sourceware/ftp/pub/binutils/releases 384 put binutils-2.4*.tar.* 385 chmod 644 binutils-2.4*.tar.* 386 quit 387 388 FIXME: Are the signatures (created by the gnupload script in step 27) 389 needed ? [The above commands upload them and nobody has complained, 390 so suggest that they are retained]. 391 392 29. Update web pages. For sourceware.org: 393 394 Create a new documentation folder on the sourceware.org web 395 pages as /sourceware/www/sourceware/htdocs/binutils/docs-2.4x. 396 397 sftp sourceware.org 398 cd /sourceware/www/sourceware/htdocs/binutils 399 mkdir docs-2.4x 400 cd docs-2.4x 401 mkdir as 402 mkdir bfd 403 mkdir binutils 404 mkdir gprof [NB/ gprofng is not needed] 405 mkdir ld 406 cd ../docs-2.4(x-1) 407 get index.html 408 409 Update the (local copy of the) index.html file to point to the 410 new documentation and mention the new version and then upload it. 411 412 cd ../docs-2.4x 413 put index.html 414 415 Make the html documentation locally with the "make html" command. 416 (This should have been done by step 25 above). 417 Then upload and rename the directories as needed. 418 (Sftp does not support recursive uploads however, so the directories 419 have to be made and populated by hand). 420 421 cd as 422 lcd <build-dir>/gas/doc/as 423 put * {be patient - this takes a long time...} 424 lcd .. 425 cd .. 426 put as.html 427 put as.pdf 428 429 cd bfd 430 lcd ../../bfd/doc/bfd 431 put * 432 cd .. 433 lcd .. 434 put bfd.html 435 put bfd.pdf 436 437 cd binutils 438 lcd ../../binutils/binutils_html <=== NB/ Path not like others 439 put * 440 cd .. 441 lcd ../doc <=== Also not like the others 442 put binutils.html 443 put binutils.pdf 444 445 cd gprof 446 lcd ../../gprof/doc/gprof 447 put * 448 cd .. 449 lcd ../.. <==== Different again 450 put gprof.html 451 put gprof.pdf 452 453 cd ld 454 lcd ../ld/doc/ld 455 put * 456 cd .. 457 lcd ../.. 458 put ld.html 459 put ld.pdf 460 461 lcd ../gprofng/doc 462 put gprofng.html 463 put gprofng.pdf 464 465 lcd ../../libctf/doc 466 put ctf-spec.html 467 put ctf-spec.pdf 468 469 lcd ../../libsframe/doc 470 put sframe-spec.html 471 put sframe-spec.pdf 472 473 Edit the top level binutils index.html file to change the links 474 to point to the new documentation. 475 476 cd ../.. 477 get index.html 478 [edit] 479 [check that it works] 480 put index.html 481 rm docs 482 ln -s docs-2.4x docs 483 quit 484 485 Check that the new web page is correct: 486 487 https://sourceware.org/binutils/ 488 489 For the www.gnu.org site you have to email webmasters (a] gnu.org 490 and ask them to copy the change(s): 491 --------------------------------------- 492 Hi FSF Webmasters, 493 494 Please could the GNU Binutils webpage at: 495 496 https://www.gnu.org/software/binutils/binutils.html 497 498 be updated to indicate that there is now a newer version available 499 (2.4x). I have already updated the related page on the sourceware 500 website so this might be useful as a template: 501 502 https://sourceware.org/binutils/ 503 504 Thanks very much. 505 506 Cheers 507 -------------------------------------- 508 509 30. Send emails to binutils (a] sourceware.org, info-gnu (a] gnu.org and 510 David Edelsohn <dje.gcc (a] gmail.com> announcing the new release. 511 Sign the email and include the checksum: 512 513 sha256sum binutils-2.4*.tar.* 514 515 (The email to Davis is so that he can update the GNU Toolchain 516 social media). Something like this: 517 ----------------------------------------------------------------------- 518 Hi Everyone, 519 520 We are pleased to announce that version 2.4x of the GNU Binutils project 521 sources have been released and are now available for download at: 522 523 https://ftp.gnu.org/gnu/binutils 524 https://sourceware.org/pub/binutils/releases/ 525 526 checksums: xxxx 527 528 As an experiment these tarballs were made with the new "-r <date>" 529 option supported by the src-release.sh script. This attempts to make 530 reproducible tarballs by sorting the files and passing the 531 "--mtime=<date>" option to tar. The date used for these tarballs was 532 obtained by running: 533 534 git log -1 --format=%cd --date=format:%F bfd/version.m4 535 536 This release contains numerous bug fixes, and also the 537 following new features: 538 539 <extract info from the NEWS files> 540 541 For more information see: 542 543 https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=gas/NEWS;;hb=refs/tags/binutils-2_4x 544 https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=ld/NEWS;hb=refs/tags/binutils-2_4x 545 https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=binutils/NEWS;hb=refs/tags/binutils-2_4x 546 547 Our thanks go out to all of the binutils contributors, past and 548 present, for helping to make this release possible. 549 550 ----------------------------------------------------------------------- 551 552 31. Clean up the source tree: 553 554 git clean -fdx . 555 556 32. Edit bfd/development.sh on the branch and set the development flag 557 to "true". (Leave the experimental flag set to "false"). Also bump 558 the version in bfd/version.m4 by adding a trailing .0, so that the 559 date suffix keeps the version lower than the trunk version. 560 Regenerate files. Commit these changes. 561 562 33. Email the binutils list telling everyone that the 2.4x branch 563 is now open for business as usual and that patches no longer 564 need special approval. 565 566 34. Examine the bfd/config.bfd file in the mainline sources and move 567 any pending obsolete targets into the definitely obsolete 568 section. Create a changelog entry and commit. 569 570 Sit back and relax, you are all done. 571 -------------------------------------------------------------------------- 572 How to perform a POINT release. 573 -------------------------------------------------------------------------- 574 575 A point release is easier than a normal release since a lot of the 576 work has already been done. The branch has been created, the 577 translations updated and the documentation uploaded. So the procedure 578 looks like this: 579 580 0. Decide that a point release is necessary. 581 582 Usually this only happens when a sufficient number of serious 583 bugs have been found and fixed since the previous release, and a 584 new official release is not imminent. 585 586 1. Tell the community that a point release is happening. Ask 587 maintainers to ensure that their ports are up to date on the 588 release branch. Ask the community if there are any bug fixes 589 which are missing from the branch. Allow some time for the 590 responses to this step. 591 592 2. Make sure that the branch sources build, test and install 593 correctly. 594 595 2.5 Prepare a list of the bugs which have been fixed. This 596 will be needed for step 8. 597 598 3. In the branch sources: 599 600 a. Update the minor release number in bfd/version.m4. 601 b. Edit bfd/development.sh, set "development=false". 602 c. Regenerate the configure files. 603 d. Remove spurious autom4te.cache files: 604 605 git clean -fdx 606 607 e. Commit the updates along with a "this-is-the-2.3x.y-release" 608 note in all of the changelogs. 609 f. Tag the branch with the new release number: 610 611 git tag -a binutils-2_3x_y 612 [optional: add "-u XXXXX" to sign with a gpg key] 613 git push origin binutils-2_3x_y 614 615 g. Check that your file creation mask will create the 616 correct file permissions. Ie: 617 618 umask 022 619 620 h. Create the release tarballs: 621 622 ./src-release -b -g -l -x binutils 623 624 i. Check that the files in the tarballs have the correct 625 permissions. 626 627 j. Clean the source tree again 628 629 git clean -fdx 630 631 k. Edit bfd/development.sh and set "development=true". 632 l. Commit this change. 633 634 4. [If paranoid - upload the tarballs to one of the FTP servers and 635 ask people to test it before going on to step 5]. 636 637 5. Upload the tarballs to ftp.gnu.org. 638 639 gnupload --to ftp.gnu.org:binutils binutils-*.tar.* 640 641 The gnupload script is in the gnulib/build-aux directory. 642 643 6. Upload the tarballs to sourceware.org: 644 645 sftp sourceware.org 646 cd /sourceware/ftp/pub/binutils/releases 647 put binutils-*.tar.* 648 chmod 644 binutils-*.tar.* 649 quit 650 651 It is OK to upload the signatures as well. 652 653 7. Update web pages. For sourceware.org: 654 655 * Log on to sourceware.org 656 * Go to /sourceware/www/sourceware/htdocs/binutils 657 * Edit index.html and update the latest release number (if this is a latest release) 658 659 For the www.gnu.org site you have to email webmasters (a] gnu.org 660 and ask them to make the change(s). 661 662 8. Send an emails to the binutils list, info-gnu (a] gnu.org and 663 David Edelsohn <dje.gcc (a] gmail.com> announcing the new release. 664 (The email to Davis is so that he can update the GNU Toolchain 665 social media). Something like this: 666 667 ------------------------------------------------------------------------ 668 Hi Everyone, 669 670 We are pleased to announce that version 2.3x.y of the GNU Binutils 671 project sources have been released and are now available for download at: 672 673 https://ftp.gnu.org/gnu/binutils 674 https://sourceware.org/pub/binutils/releases/ 675 676 This is a point release over the previous 2.3x version, containing bug 677 fixes but no new features. 678 679 Our thanks go out to all of the binutils contributors, past and 680 present, for helping to make this release possible. 681 682 Here is a list of the bugs that have been fixed: 683 xx 684 xx 685 xx 686 xx 687 -------------------------------------------------------------------------- 688 689 9. Create a new Bugzilla entry for the point release. 690 691 https://sourceware.org/bugzilla/editversions.cgi?product=binutils 692 693 And a new milestone too: 694 695 https://sourceware.org/bugzilla/editmilestones.cgi?product=binutils 696 698 Copyright (C) 2017-2024 Free Software Foundation, Inc. 699 700 Copying and distribution of this file, with or without modification, 701 are permitted in any medium without royalty provided the copyright 702 notice and this notice are preserved. 703
Indexes created Tue Jul 21 00:24:56 UTC 2026