15. Releasing GDB

15.1 Obsolete any code

Before anything else, poke the other developers (and around the source code) to see there is anything that can be removed from GDB (an old target, an unused file).

Obsolete code is identified by adding an OBSOLETE prefix to every line. Doing this means that it is easy to identify obsolete code when grepping through the sources.

The process has a number of steps and is intentionally slow -- this is to mainly ensure that people have had a reasonable chance to respond. Remember, everything on the internet takes a week.

• announce the change on GDB mailing list
• wait a week or so
• announce the change on GDB Announcement mailing list
• wait a week or so
• go through and edit all relevant files and lines (e.g., in `configure.tgt') so that they are prefixed with the word OBSOLETE.

Maintainer note: Removing old code, while regrettable, is a good thing. Firstly it helps the developers by removing code that is either no longer relevant or simply wrong. Secondly since it removes any history associated with the file (effectively clearing the slate) the developer has a much freer hand when it comes to fixing broken files.

15.2 Before the branch

The most important objective at this stage is to find and fix simple changes that become a pain to track once the branch is created. For instance, configuration problems that stop GDB from even building. If you can't get the problem fixed, document it in the `gdb/PROBLEMS' file.

Organize and announce the schedule.

The following is a possible schedule. It is based on the rule-of-thumb that everything on the Internet takes a week. You may want to even increase those times further since an analysis of the actual data strongly suggests that the below is far to aggressive.

• announce it
• wait a week
• announce branch date
• wait a week
• Cut the branch
• wait a week
• start enjoying all the fun

As an aside, the branch tag name is probably regrettable vis:

gdb_N_M-YYYY-MM-DD-{branch,branchpoint}

Refresh any imported files.

A number of files are taken from external repositories. They include:

• `texinfo/texinfo.tex'
• `config.guess' et. al.

and should be refreshed.

Prompt for `gdb/NEWS'

People always forget. Send a post reminding them but also if you know something interesting happened add it your self.

Review `gdb/README'

Grab one of the nightly snapshots and then walk through the `gdb/README' looking for anything that can be improved.

Check the ARI

ARI is an awk script (Awk Regression Indicator?) that checks for a number of errors and coding conventions. The checks include things like using malloc instead of xmalloc and file naming problems. There shouldn't be any regressions.

15.3 Cut the branch

The dirty work

I think something like the below was used:

$ d=`date -u +%Y-%m-%d` $ echo $d 2002-01-24 $ cvs -f -d /cvs/src rtag -D $d-gmt \ gdb_5_1-$d-branchpoint insight+dejagnu $ cvs -f -d /cvs/src rtag -b -r gdb_V_V-$d-branchpoint \ gdb_5_1-$d-branch insight+dejagnu $

• the -D YYYY-MM-DD-gmt forces the branch to an exact date/time.
• the trunk is first taged so that the branch point can easily be found
• Insight (which includes GDB) and dejagnu are tagged at the same time

Post the branch info

Update the web and news pages

Tweak cron to track the new branch

15.4 Stabilize the branch

Something goes here.

15.5 Create a Release

This procedure can be followed when creating beta and final final releases. With a beta many of the steps can be skipped.

Establish a few defaults.

$ b=gdb_5_1-2001-07-29-branch $ v=5.1.1 $ t=/sourceware/snapshot-tmp/gdbadmin-tmp $ echo $t/$b/$v $ mkdir -p $t/$b/$v $ cd $t/$b/$v $ pwd /sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_1-2001-07-29-branch/5.1.1 $ which autoconf /home/gdbadmin/bin/autoconf $

NB: Check the autoconf version carefully. You want to be using the version taken from the binutils snapshot directory. It is most likely that your system's installed version (`/usr/bin'?) is probably correct.

Check out the relevant modules:

$ for m in gdb insight dejagnu do ( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m ) done $

NB: The reading of `.cvsrc' is disabled (`-f') so that there isn't any confusion between what is written here and what your local CVS really does.

Update relevant files.

`gdb/NEWS'

Major releases get their comments added as part of the mainline. Minor releases should probably mention any significant bugs that were fixed.

Don't forget to update the ChangeLog.

$ emacs gdb/src/gdb/NEWS ... c-x 4 a ... c-x c-s c-x c-c $ cp gdb/src/gdb/NEWS insight/src/gdb/NEWS $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog

`gdb/README'

You'll need to update: the version, the update date, and who did it.

$ emacs gdb/src/gdb/README ... c-x 4 a ... c-x c-s c-x c-c $ cp gdb/src/gdb/README insight/src/gdb/README $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog

Maintainer note: Hopefully the README file was reviewed before the initial branch was cut so just a simple substitute is needed to get it updated.

Maintainer note: Other projects generate `README' and `INSTALL' from the core documentation. This might be worth pursuing.

`gdb/version.in'

$ echo $v > gdb/src/gdb/version.in $ emacs gdb/src/gdb/version.in ... c-x 4 a ... c-x c-s c-x c-c $ cp gdb/src/gdb/version.in insight/src/gdb/version.in $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog

`dejagnu/src/dejagnu/configure.in'

Dejagnu is more complicated. The version number is a parameter to AM_INIT_AUTOMAKE. Tweak it to read something like gdb-5.1.1.

Re-generate configure.

Add a ChangeLog.

Do the dirty work

This is identical to the process used when creating the daily snapshot.

$ for m in gdb insight dejagnu do ( cd $m/src && gmake -f Makefile.in $m.tar.bz2 ) done

Check the source files

You're looking for files that have mysteriously disappeared as the distclean has the habit of deleting files it shouldn't. Watch out for the `version.in' update cronjob.

$ ( cd gdb/src && cvs -f -q -n update ) M djunpack.bat ? proto-toplev ? gdb-5.1.1.tar.bz2 M gdb/ChangeLog M gdb/NEWS M gdb/README M gdb/version.in ? gdb/p-exp.tab.c ? gdb/doc/gdb.info-11 ? gdb/doc/gdb.info-12 ? gdb/doc/gdb.info-13 ? gdb/doc/gdb.info-14 ? gdb/doc/gdb.info-15 ? gdb/doc/gdbint.info-4 ? gdb/doc/gdbint.info-5 $

Don't worry about the `gdb.info-??' or `gdb/p-exp.tab.c'. They were generated (and yes `gdb.info-1' was also generated only something strange with CVS means that they didn't get supressed). Fixing it would be nice though.

Re-pack the release with gzip

$ cp */*/*.bz2 . $ bunzip2 -k -v *.bz2 $ gzip -9 -v *.tar

NB: A pipe such as bunzip2 < xxx.bz2 | gzip -9 > xxx.gz shouldn't be used since, in that mode, gzip doesn't know the file name information and consequently can't include it. This is also why the release process runs tar and bzip2 as separate passes.

Maintainer note: The release process could be changed to create `.tar' rather than `.tar.bz2' files.

15.6 Check the release

Grab the `gdb.tar.bz2', copy it to your local machine and then try a simple build using it.

If this is a pre-release just copy the `.bz2' files to the snapshot directory and skip the remaining steps.

If it is a final release, also make it available under a bogus name so that others can download and check it.

Maintainer note: This adds an extra day to the release process but is very much worth it. Other developers are given the oportunity to check that things like your `NEWS' entries are correct or that other changes actually work.

15.7 Release the tar ball

This is where, unfortunatly, the notes just get vague.

Install on sware

$ cp *.bz2 *.gz ~ftp/pub/gdb/releases

Create and update the web pages.

Try the following:

• create the directory `htdocs/version' (e.g., `htdocs/5.1.1'
• copy `index.html' and `ANNOUNCE' from the previous release into the `htdocs/version' directory and edit for content. Things like the MD5 sums, ls -l output, the version number and so on will need updating. Add NEWS entries to the `ANNOUNCE'. This ensures that the previous announcement is kept somewhere handy.
• copy the `NEWS' from the distro into the `htdocs/version' directory, trim down to just the most recent news items
• Add a short (identical) announcement to both `htdocs/index.html' and `htdocs/news/index.html'
• edit the script `htdocs/index.sh' to link in the new release number. Run it across all `index.html' files vis ./index.sh index.html */index.html.
• grep the `htdocs' tree for references to the previous release version (`htdocs/download/index.html')

Maintainer note: This step is too fragile -- it is too easy to mis one of the entries and forget to update it.

Generate online docs

You need to find the magic command that is used to generate the online docs from the `.tar.bz2'. The best way is to look in the output from one of the nightly cronjobs and then just edit accordingly. Something like:

$ ~/ss/update-web-docs \ ~ftp/pub/gdb/releases/gdb-5.1.1.tar.bz2 \ $PWD/www \ /www/sourceware/htdocs/gdb/5.1.1/onlinedocs \ gdb

Something about `ANNOUNCEMENT'

Send the `ANNOUNCEMENT' file you created above to:

• GDB Announcement mailing list
• The gnu announce list (but delay it a day or so to let things get out).

Install it on GNU

At the time of writing, the GNU machine was gnudist.gnu.org in `~ftp/gnu/gdb' (I think, I'm still waiting for it to copy into my home directory).

15.8 Cleanup

Commit outstanding changes

In particular you'll need to commit the changes to:

• `gdb/ChangeLog'
• `gdb/version.in'
• `gdb/NEWS'
• `gdb/README'

Tag the release

Something like:

$ d=`date -u +%Y-%m-%d` $ echo $d 2002-01-24 $ ( cd insight/src/gdb && cvs -f -q update ) $ ( cd insight/src && cvs -f -q tag gdb_5_1_1-$d-release )

Insight is used since that contains more of the release than GDB (yes dejagnu doesn't get tagged but I think we can live with that.).

Restart `gdb/version.in'

If `gdb/version.in' does not contain an ISO date such as 2002-01-24 then the daily cronjob won't update it. Having committed all the release changes it can be set to `5.1.0_0000-00-00-cvs' which will restart things (yes the _ is important - it affects the snapshot process).

Don't forget the `ChangeLog'.

Merge into trunk

The files committed to the branch may also need changes merged into the trunk.

15.9 Post release

Remove any OBSOLETE code.