Next: , Previous: Start of New Year Procedure, Up: Top



20 Releasing gdb

20.1 Branch Commit Policy

The branch commit policy is pretty slack. gdb releases 5.0, 5.1 and 5.2 all used the below:

Pragmatics: Provided updates are restricted to non-core functionality there is little chance that a broken change will be fatal. This means that changes such as adding a new architectures or (within reason) support for a new host are considered acceptable.

20.2 Obsoleting code

Before anything else, poke the other developers (and around the source code) to see if 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 something that has been obsoleted when greping through the sources.

The process is done in stages — this is mainly to ensure that the wider gdb community has a reasonable opportunity to respond. Remember, everything on the Internet takes a week.

  1. Post the proposal on the GDB mailing list Creating a bug report to track the task's state, is also highly recommended.
  2. Wait a week or so.
  3. Post the proposal on the GDB Announcement mailing list.
  4. Wait a week or so.
  5. Go through and edit all relevant files and lines so that they are prefixed with the word OBSOLETE.
  6. Wait until the next GDB version, containing this obsolete code, has been released.
  7. Remove the obsolete code.

Maintainer note: While removing old code is regrettable it is hopefully better for gdb's long term development. 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.

20.3 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.

Prompt for gdb/NEWS

People always forget. Send a post reminding them but also if you know something interesting happened add it yourself. The schedule script will mention this in its e-mail.

Review gdb/README

Grab one of the nightly snapshots and then walk through the gdb/README looking for anything that can be improved. The schedule script will mention this in its e-mail.

Refresh any imported files.

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

Check the ARI

A.R.I. is an awk script (Awk Regression Index ;-) 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.

20.3.1 Review the bug data base

Close anything obviously fixed.

20.3.2 Check all cross targets build

The targets are listed in gdb/MAINTAINERS.

20.4 Cut the Branch

Create the branch

     $  u=5.1
     $  v=5.2
     $  V=`echo $v | sed 's/\./_/g'`
     $  D=`date -u +%Y-%m-%d`
     $  echo $u $V $D
     5.1 5_2 2002-03-03
     $  echo cvs -f -d :ext:sourceware.org:/cvs/src rtag \
     -D $D-gmt gdb_$V-$D-branchpoint insight
     cvs -f -d :ext:sourceware.org:/cvs/src rtag
     -D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight
     $  ^echo ^^
     ...
     $  echo cvs -f -d :ext:sourceware.org:/cvs/src rtag \
     -b -r gdb_$V-$D-branchpoint gdb_$V-branch insight
     cvs -f -d :ext:sourceware.org:/cvs/src rtag \
     -b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight
     $  ^echo ^^
     ...
     $

Update version.in

     $  u=5.1
     $  v=5.2
     $  V=`echo $v | sed 's/\./_/g'`
     $  echo $u $v$V
     5.1 5_2
     $  cd /tmp
     $  echo cvs -f -d :ext:sourceware.org:/cvs/src co \
     -r gdb_$V-branch src/gdb/version.in
     cvs -f -d :ext:sourceware.org:/cvs/src co
      -r gdb_5_2-branch src/gdb/version.in
     $  ^echo ^^
     U src/gdb/version.in
     $  cd src/gdb
     $  echo $u.90-0000-00-00-cvs > version.in
     $  cat version.in
     5.1.90-0000-00-00-cvs
     $  cvs -f commit version.in

Update the web and news pages

Something?

Tweak cron to track the new branch

The file gdbadmin/cron/crontab contains gdbadmin's cron table. This file needs to be updated so that:

See the file gdbadmin/cron/README for how to install the updated cron table.

The file gdbadmin/ss/README should also be reviewed to reflect any changes. That file is copied to both the branch/ and current/ snapshot directories.

Update the NEWS and README files

The NEWS file needs to be updated so that on the branch it refers to changes in the current release while on the trunk it also refers to changes since the current release.

The README file needs to be updated so that it refers to the current release.

Post the branch info

Send an announcement to the mailing lists:

Pragmatics: The branch creation is sent to the announce list to ensure that people people not subscribed to the higher volume discussion list are alerted.

The announcement should include:

20.5 Stabilize the branch

Something goes here.

20.6 Create a Release

The process of creating and then making available a release is broken down into a number of stages. The first part addresses the technical process of creating a releasable tar ball. The later stages address the process of releasing that tar ball.

When making a release candidate just the first section is needed.

20.6.1 Create a release candidate

The objective at this stage is to create a set of tar balls that can be made available as a formal release (or as a less formal release candidate).

Freeze the branch

Send out an e-mail notifying everyone that the branch is frozen to gdb-patches@sourceware.org.

Establish a few defaults.
     $  b=gdb_5_2-branch
     $  v=5.2
     $  t=/sourceware/snapshot-tmp/gdbadmin-tmp
     $  echo $t/$b/$v
     /sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
     $  mkdir -p $t/$b/$v
     $  cd $t/$b/$v
     $  pwd
     /sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
     $  which autoconf
     /home/gdbadmin/bin/autoconf
     $

Notes:

Check out the relevant modules:
     $  for m in gdb insight
     do
     ( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m )
     done
     $

Note:

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 include the ChangeLog entry.

          $  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.
  • 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
          $  cat gdb/src/gdb/version.in
          5.2
          $  emacs gdb/src/gdb/version.in
          ...
          c-x 4 a
          ... Bump to version ...
          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
     
Do the dirty work

This is identical to the process used to create the daily snapshot.

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

If the top level source directory does not have src-release (gdb version 5.3.1 or earlier), try these commands instead:

     $  for m in gdb insight
     do
     ( cd $m/src && gmake -f Makefile.in $m.tar )
     done
Check the source files

You're looking for files that have mysteriously disappeared. 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
     ? gdb-5.1.91.tar
     ? proto-toplev
     ... lots of generated files ...
     M gdb/ChangeLog
     M gdb/NEWS
     M gdb/README
     M gdb/version.in
     ... lots of generated files ...
     $

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 suppressed). Fixing it would be nice though.

Create compressed versions of the release
     $  cp */src/*.tar .
     $  cp */src/*.bz2 .
     $  ls -F
     gdb/ gdb-5.2.tar insight/ insight-5.2.tar
     $  for m in gdb insight
     do
     bzip2 -v -9 -c $m-$v.tar > $m-$v.tar.bz2
     gzip -v -9 -c $m-$v.tar > $m-$v.tar.gz
     done
     $

Note:

20.6.2 Sanity check the tar ball

Pick a popular machine (Solaris/PPC?) and try the build on that.

     $  bunzip2 < gdb-5.2.tar.bz2 | tar xpf -
     $  cd gdb-5.2
     $  ./configure
     $  make
     ...
     $  ./gdb/gdb ./gdb/gdb
     GNU gdb 5.2
     ...
     (gdb)  b main
     Breakpoint 1 at 0x80732bc: file main.c, line 734.
     (gdb)  run
     Starting program: /tmp/gdb-5.2/gdb/gdb
     
     Breakpoint 1, main (argc=1, argv=0xbffff8b4) at main.c:734
     734       catch_errors (captured_main, &args, "", RETURN_MASK_ALL);
     (gdb)  print args
     $1 = {argc = 136426532, argv = 0x821b7f0}
     (gdb)

20.6.3 Make a release candidate available

If this is a release candidate then the only remaining steps are:

  1. Commit version.in and ChangeLog
  2. Tweak version.in (and ChangeLog to read L.M.N-0000-00-00-cvs so that the version update process can restart.
  3. Make the release candidate available in ftp://sourceware.org/pub/gdb/snapshots/branch
  4. Notify the relevant mailing lists ( gdb@sourceware.org and gdb-testers@sourceware.org that the candidate is available.

20.6.4 Make a formal release available

(And you thought all that was required was to post an e-mail.)

Install on sware

Copy the new files to both the release and the old release directory:

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

Clean up the releases directory so that only the most recent releases are available (e.g. keep 5.2 and 5.2.1 but remove 5.1):

     $  cd ~ftp/pub/gdb/releases
     $  rm ...

Update the file README and .message in the releases directory:

     $  vi README
     ...
     $  rm -f .message
     $  ln README .message
Update the web pages.
htdocs/download/ANNOUNCEMENT
This file, which is posted as the official announcement, includes:
  • General announcement.
  • News. If making an M.N.1 release, retain the news from earlier M.N release.
  • Errata.

htdocs/index.html
htdocs/news/index.html
htdocs/download/index.html
These files include:
  • Announcement of the most recent release.
  • News entry (remember to update both the top level and the news directory).
These pages also need to be regenerate using index.sh.
download/onlinedocs/
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 cron jobs and then just edit accordingly. Something like:
          $  ~/ss/update-web-docs \
           ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
           $PWD/www \
           /www/sourceware/htdocs/gdb/download/onlinedocs \
           gdb
     

download/ari/
Just like the online documentation. Something like:
          $  /bin/sh ~/ss/update-web-ari \
           ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
           $PWD/www \
           /www/sourceware/htdocs/gdb/download/ari \
           gdb
     
Shadow the pages onto gnu

Something goes here.

Install the gdb tar ball on GNU

At the time of writing, the GNU machine was gnudist.gnu.org in ~ftp/gnu/gdb.

Make the ANNOUNCEMENT

Post the ANNOUNCEMENT file you created above to:

20.6.5 Cleanup

The release is out but you're still not finished.

Commit outstanding changes

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

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_2-$d-release )

Insight is used since that contains more of the release than gdb.

Mention the release on the trunk

Just put something in the ChangeLog so that the trunk also indicates when the release was made.

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.2.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.

Revise the release schedule

Post a revised release schedule to GDB Discussion List with an updated announcement. The schedule can be generated by running:

     $  ~/ss/schedule `date +%s` schedule

The first parameter is approximate date/time in seconds (from the epoch) of the most recent release.

Also update the schedule cronjob.

20.7 Post release

Remove any OBSOLETE code.