1 README for MAKING BINUTILS RELEASES
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
7 https://www.gnu.org/software/gnulib/
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
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
18 -------------------------------------------------
19 How to perform a release.
20 -------------------------------------------------
22 1. Send an email out warning contributors about the forthcoming
23 branch. Set a date for the branch (weekends are better because
26 2. When the branch date is near: Update the libiberty and config
27 directories and the top level Makefile and configure files. Also
28 consider updating the toplevel libtool files.
31 Approx time to complete from here: 2 hours ....
33 2.5 If you have not built from the sources recently then now is the
34 time to check that they still work...
36 3. When branch day arrives add markers for the upcoming release to
37 the NEWS files in gas, ld, and binutils. No need to update NEWS
38 in the gold directory - it has its own release numbering.
40 Likewise for the ChangeLog files in: bfd, binutils, config, cpu,
41 elfcpp, gas, gold, gprof, include, ld, libctf, opcodes and toplevel.
43 Add a note of the name of the new branch to binutils/BRANCHES.
47 4. Create the release branch using:
49 git branch binutils-2_40-branch
50 git push origin binutils-2_40-branch
52 If you get a message like:
54 remote: fatal: Invalid revision range 0000000000000000000000000000000000000000..f974f26cb16cc6fe3946f163c787a05e713fb77b
56 It appears that this can be ignored...
58 5. Make sure that the branch is there. IE check out the branch sources:
60 git clone ssh://sourceware.org/git/binutils-gdb.git -b binutils-2_40-branch 2.40
62 If you get a message about being in a "detached head" state, something
65 Keep the checked out sources - they are going to be needed in future
68 6. Update "BINUTILS_BRANCH" in gdbadmin's crontab:
70 Log in as gdbadmin on sourceware.org, and then:
74 [change BINUTILS_BRANCH]
78 If you do not have access to this account, please feel free to
79 ask Joel Brobecker <brobecker AT adacore DOT com>.
81 7. Rename the current HEAD version entry in Bugzilla, and create a
82 new one. E.g. rename "2.38 (HEAD)" to 2.38, and create
85 https://sourceware.org/bugzilla/editversions.cgi?product=binutils
87 8. Update bfd/version.m4 on HEAD to indicate that is now a snapshot
88 of the next release and the BRANCH to indicated that it is almost
89 ready for the release.
91 So if the release is going to be 2.40 then the version number on
92 the BRANCH should be set to 2.39.90 - ie almost, but not quite 2.40,
93 and the version number on the MAINLINE should be set to 2.40.50 -
94 ie half way to 2.41 release.
96 So the branch bfd/version.m4 has:
98 m4_define([BFD_VERSION], [2.39.90])
100 and the mainline has:
102 m4_define([BFD_VERSION], [2.40.50])
104 Regenerate various files on both branch and HEAD by configuring
105 with "--enable-maintainer-mode --enable-gold --enable-shared" and then building
106 with "make all-binutils all-gas all-gold all-gprof all-gprofng all-ld"
108 Add ChangeLog entries for the updated files. Commit the changes.
109 Make sure that this includes the .pot files as well as the
110 configure and makefiles.
112 9. Create an initial pre-release:
114 a. Remove any auto-generated files, in order to force the
115 src-release script to rebuild them.
120 b. Create a source tarball of the BRANCH sources:
122 ./src-release.sh -x binutils
124 c. Build a test target using this tarball.
126 cp binutils-2.39.90.tar.xz /dev/shm
128 tar xvf binutils-2.39.90.tar.xz
131 ../binutils-2.39.90/configure --quiet --enable-gold
135 If there are problems, fix them.
137 d. Upload the pre-release snapshot to the sourceware FTP site:
139 scp binutils-2.39.90.tar.xz sourceware.org:/var/ftp/pub/binutils/snapshots
140 ssh sourceware.org sha256sum ~ftp/pub/binutils/snapshots/binutils-2.39.90.tar.xz
142 e. Clean up the source directory again.
146 10. Tell the Translation Project where to find the new tarball.
147 <coordinator@translationproject.org>
148 qv: https://translationproject.org/html/maintainers.html
150 ------------------------------------------------------------------------
151 Dear Translation Project
153 The 2.40 release branch has been created for the GNU Binutils project.
155 A snapshot of the branch sources can be found here:
157 https://sourceware.org/pub/binutils/snapshots/binutils-2.39.90.tar.xz
159 We hope to make the official release of the sources on the <DATE>
160 although that could change if there are important bugs that need to
161 be fixed before the release.
162 ------------------------------------------------------------------------
164 11. Announce the availability of the snapshot and the branch on the
165 binutils mailing list. Set a date for when the release will
166 actually happen. Something like:
168 ------------------------------------------------------------------------
171 The <NEW_VERSION> branch has now been created:
173 git clone git://sourceware.org/git/binutils-gdb.git -b binutils-<NEW_VERSION>-branch
175 A snapshot of the sources is also available here:
177 https://sourceware.org/pub/binutils/snapshots/binutils-<OLD_VERSION>.90.tar.xz
179 Please could all patches for the branch be run by me.
180 The rules for the branch are:
183 * Target specific bug fixes are OK.
184 * Generic bug fixes are OK if they are important and widely tested.
185 * Documentation updates/fixes are OK.
186 * Translation updates are OK.
187 * Fixes for testsuite failures are OK.
189 Ideally I would like to make the release happen in two weeks time,
190 i.e. <DATE>. Which I hope will be enough time for everyone
191 to get their final fixes in.
192 ------------------------------------------------------------------------
194 12. Build various different toolchains, test them and nag
195 maintainers to fix any testsuite failures for their
198 ==============================================================================
200 When the time comes to actually make the release....
203 20. Make sure that the branch sources still build, test and install
204 correctly. Make sure that the sources are clean, without any
205 patch files (.reg .orig *~) left over.
210 21. a. Update the release number in bfd/version.m4 on the release
211 branch to a whole new minor version number, without a point
212 value. Eg "2.39.90" becomes "2.40".
214 b. Change bfd/development.sh to set all values to "false".
216 c. Regenerate the configure and makefiles. And *info* files.
218 make all-gas all-ld all-binutils all-gprof all-gold all-gprofng
221 d. Create a ChangeLog from the git refs for all of the commits
222 from when changelog entries were no longer required:
224 gitlog-to-changelog --since=2021-07-03 > ChangeLog.git
225 git add ChangeLog.git
227 The gitlog-to-changelog script is part of the sources
228 of the "config" project.
230 e. Add ChangeLog entries for all of the updates and add a
231 "this-is-the-2.38-release" comment and commit.
236 22. Check that your file creation mask will create the
237 correct file permissions. Eg:
242 Remove any spurious autom4te.cache files left over from the
247 23. Note - check to see if any new files have been added to the top
248 level of the source directory, but which are not in the
249 DEVO_SUPPORT variable in the src-release.sh script. If they are
250 needed then add them.
252 Create the release tarballs:
254 ./src-release.sh -b -g -l -x binutils
256 OR ... for a more reproducible tarball:
258 ./src-release.sh -b -g -l -x -r `git log -1 --format=%cd --date=format:%F bfd/version.m4` binutils
260 24. Check that the files in the tarballs have the correct
263 tar tvf binutils-*.tar.bz2 | grep -e "---"
265 Also check that the man files are not empty. (cf PR 28144).
267 tar tvf binutils-*.tar.xz | grep -e "\.1"
269 25. Sanity check the release on x86_64-pc-linux-gnu by building and
270 running the testsuites (gas, gold, binutils and ld). Make the
271 source directory read-only before building. (Note - the gprofng
272 sources need a writeable doc/ directory. This is a bug that needs
274 Also test "make install".
275 If necessary fix any problems.
280 tar xvf <path-to-sources>/binutils-2.*.tar.lz
281 chmod -R -w binutils-2.*
282 chmod +w binutils-2.*/gprofng/doc
285 ../binutils-2.*/configure --quiet --enable-gold --prefix=`pwd`/install --enable-plugins --enable-shared
286 make all-gas all-gold all-ld all-binutils all-gprof all-gprofng
287 make check-gas check-binutils check-ld check-gold
288 make install-gas install-gold install-ld install-binutils install-gprofng
290 # Needed for step 29...
295 26. Tag the branch with the new release number:
296 [optional: add "-u XXXXX" to sign with a gpg key]
297 enter a tag message such as: "Official GNU Binutils 2.3x release"
299 git tag -a binutils-2_40 -u DD9E3C4F <=== Be careful to get the tag right
301 NB/ If you do sign the binaries make sure to use a key
302 that has been published with the FSF.
304 Then push the release:
306 git push origin binutils-2_40
308 If you get an error message along the lines of:
309 "Invalid revision range ..." you can ignore it.
311 27. Upload the tarballs to ftp.gnu.org.
313 gnupload --to ftp.gnu.org:binutils binutils-2.3*.tar.*
315 Be prepared to provide the password for the key, if you
318 The gnupload script is in the gnulib/build-aux directory.
320 Check for an email response from the upload. If necessary
323 28. Upload the tarballs (and signatures) to sourceware.org:
326 cd /sourceware/ftp/pub/binutils/releases
327 put binutils-2.3*.tar.*
328 chmod 644 binutils-2.3*.tar.*
331 FIXME: Are the signatures (created by the gnupload script in step 27)
332 needed ? [The above commands upload them and nobody has complained,
333 so suggest that they are retained].
335 29. Update web pages. For sourceware.org:
337 Create a new documentation folder on the sourceware.org web
338 pages as /sourceware/www/sourceware/htdocs/binutils/docs-2.3x.
341 cd /sourceware/www/sourceware/htdocs/binutils
352 Update the (local copy of the) index.html file to point to the
353 new documentation and mention the new version and then upload it.
358 Make the html documentation locally with the "make html" command
359 (see step 25 above). Then upload and rename the directories as
360 needed. (sftp does not appear to support recursive uploads
361 however, so the directories had to be made by hand, as shown above).
364 lcd <build-dir>/gas/doc/as
365 put * {be patient - this takes a long time...}
372 lcd ../../bfd/doc/bfd
380 lcd ../../binutils/binutils <=== NB/ Path not like others
388 lcd ../../gprof/doc/gprof
403 lcd ../../gprofng/doc
407 Edit the top level binutils index.html file to change the links
408 to point to the new documentation.
418 Check that the new web page is correct:
420 https://sourceware.org/binutils/
422 For the www.gnu.org site you have to email webmasters@gnu.org
423 and ask them to make the change(s):
424 ---------------------------------------
427 Please could the GNU Binutils webpage at:
429 https://www.gnu.org/software/binutils/binutils.html
431 be updated to indicate that there is now a newer version available
432 (2.3x). I have already updated the related page on the sourceware
433 website so this might be useful as a template:
435 https://sourceware.org/binutils/
440 --------------------------------------
442 30. Send emails to binutils@sourceware.org, info-gnu@gnu.org and
443 David Edelsohn <dje.gcc@gmail.com> announcing the new release.
444 Sign the email and include the checksum:
446 sha256sum binutils-2.3*.tar.*
448 (The email to Davis is so that he can update the GNU Toolchain
449 social media). Something like this:
450 -----------------------------------------------------------------------
453 We are pleased to announce that version 2.3x of the GNU Binutils project
454 sources have been released and are now available for download at:
456 https://ftp.gnu.org/gnu/binutils
457 https://sourceware.org/pub/binutils/releases/
461 This release contains numerous bug fixes, and also the
462 following new features:
464 <extract info from the NEWS files>
466 For more information see:
468 https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=gas/NEWS;;hb=refs/tags/binutils-2_39
469 https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=ld/NEWS;hb=refs/tags/binutils-2_39
470 https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=binutils/NEWS;hb=refs/tags/binutils-2_39
472 Our thanks go out to all of the binutils contributors, past and
473 present, for helping to make this release possible.
475 -----------------------------------------------------------------------
477 31. Clean up the source tree:
481 32. Edit bfd/development.sh on the branch and set the development flag
482 to "true". (Leave the experimental flag set to "false"). Also bump
483 the version in bfd/version.m4 by adding a trailing .0, so that the
484 date suffix keeps the version lower than the trunk version.
485 Regenerate files. Commit these changes.
487 33. Email the binutils list telling everyone that the 2.3x branch
488 is now open for business as usual and that patches no longer
489 need special approval.
491 34. Examine the bfd/config.bfd file in the mainline sources and move
492 any pending obsolete targets into the definitely obsolete
493 section. Create a changelog entry and commit.
498 --------------------------------------------------------------------------
499 How to perform a POINT release.
500 --------------------------------------------------------------------------
502 A point release is easier than a normal release since a lot of the
503 work has already been done. The branch has been created, the
504 translations updated and the documentation uploaded. So the procedure
507 0. Decide that a point release is necessary.
509 Usually this only happens when a sufficient number of serious
510 bugs have been found and fixed since the previous release, and a
511 new official release is not imminent.
513 1. Tell the community that a point release is happening. Ask
514 maintainers to ensure that their ports are up to date on the
515 release branch. Ask the community if there are any bug fixes
516 which are missing from the branch. Allow some time for the
517 responses to this step.
519 2. Make sure that the branch sources build, test and install
522 2.5 Prepare a list of the bugs which have been fixed. This
523 will be needed for step 8.
525 3. In the branch sources:
527 a. Update the minor release number in bfd/version.m4.
528 b. Edit bfd/development.sh, set "development=false".
529 c. Regenerate the configure files.
530 d. Remove spurious autom4te.cache files:
534 e. Commit the updates along with a "this-is-the-2.3x.y-release"
535 note in all of the changelogs.
536 f. Tag the branch with the new release number:
538 git tag -a binutils-2_3x_y
539 [optional: add "-u XXXXX" to sign with a gpg key]
540 git push origin binutils-2_3x_y
542 g. Check that your file creation mask will create the
543 correct file permissions. Ie:
547 h. Create the release tarballs:
549 ./src-release -b -g -l -x binutils
551 i. Check that the files in the tarballs have the correct
554 j. Clean the source tree again
558 k. Edit bfd/development.sh and set "development=true".
559 l. Commit this change.
561 4. [If paranoid - upload the tarballs to one of the FTP servers and
562 ask people to test it before going on to step 5].
564 5. Upload the tarballs to ftp.gnu.org.
566 gnupload --to ftp.gnu.org:binutils binutils-*.tar.*
568 The gnupload script is in the gnulib/build-aux directory.
570 6. Upload the tarballs to sourceware.org:
573 cd /sourceware/ftp/pub/binutils/releases
575 chmod 644 binutils-*.tar.*
578 It is OK to upload the signatures as well.
580 7. Update web pages. For sourceware.org:
582 * Log on to sourceware.org
583 * Go to /sourceware/www/sourceware/htdocs/binutils
584 * Edit index.html and update the latest release number (if this is a latest release)
586 For the www.gnu.org site you have to email webmasters@gnu.org
587 and ask them to make the change(s).
589 8. Send an emails to the binutils list, info-gnu@gnu.org and
590 David Edelsohn <dje.gcc@gmail.com> announcing the new release.
591 (The email to Davis is so that he can update the GNU Toolchain
592 social media). Something like this:
594 ------------------------------------------------------------------------
597 We are pleased to announce that version 2.3x.y of the GNU Binutils
598 project sources have been released and are now available for download at:
600 https://ftp.gnu.org/gnu/binutils
601 https://sourceware.org/pub/binutils/releases/
603 This is a point release over the previous 2.3x version, containing bug
604 fixes but no new features.
606 Our thanks go out to all of the binutils contributors, past and
607 present, for helping to make this release possible.
609 Here is a list of the bugs that have been fixed:
614 --------------------------------------------------------------------------
616 9. Create a new Bugzilla entry for the point release.
618 https://sourceware.org/bugzilla/editversions.cgi?product=binutils
620 And a new milestone too:
622 https://sourceware.org/bugzilla/editmilestones.cgi?product=binutils
624 Copyright (C) 2017-2022 Free Software Foundation, Inc.
626 Copying and distribution of this file, with or without modification,
627 are permitted in any medium without royalty provided the copyright
628 notice and this notice are preserved.