GNU Info
(gdbint.info)Releasing GDB
Releasing GDB
*************
Versions and Branches
=====================
Version Identifiers
-------------------
GDB's version is determined by the file `gdb/version.in'.
GDB's mainline uses ISO dates to differentiate between versions.
The CVS repository uses YYYY-MM-DD-cvs while the corresponding snapshot
uses YYYYMMDD.
GDB's release branch uses a slightly more complicated scheme. When
the branch is first cut, the mainline version identifier is prefixed
with the MAJOR.MINOR from of the previous release series but with .90
appended. As draft releases are drawn from the branch, the minor minor
number (.90) is incremented. Once the first release (M.N) has been
made, the version prefix is updated to M.N.0.90 (dot zero, dot ninety).
Follow on releases have an incremented minor minor version number (.0).
Using 5.1 (previous) and 5.2 (current), the example below
illustrates a typical sequence of version identifiers:
5.1.1
final release from previous branch
2002-03-03-cvs
main-line the day the branch is cut
5.1.90-2002-03-03-cvs
corresponding branch version
5.1.91
first draft release candidate
5.1.91-2002-03-17-cvs
updated branch version
5.1.92
second draft release candidate
5.1.92-2002-03-31-cvs
updated branch version
5.1.93
final release candidate (see below)
5.2
official release
5.2.0.90-2002-04-07-cvs
updated CVS branch version
5.2.1
second official release
Notes:
* Minor minor minor draft release candidates such as 5.2.0.91 have
been omitted from the example. Such release candidates are,
typically, never made.
* For 5.1.93 the bziped tar ball `gdb-5.1.93.tar.bz2' is just the
official `gdb-5.2.tar' renamed and compressed.
To avoid version conflicts, vendors are expected to modify the file
`gdb/version.in' to include a vendor unique alphabetic identifier (an
official GDB release never uses alphabetic characters in its version
identifer).
Since GDB does not make minor minor minor releases (e.g., 5.1.0.1)
the conflict between that and a minor minor draft release identifier
(e.g., 5.1.0.90) is avoided.
Branches
--------
GDB draws a release series (5.2, 5.2.1, ...) from a single release
branch (gdb_5_2-branch). Since minor minor minor releases (5.1.0.1)
are not made, the need to branch the release branch is avoided (it also
turns out that the effort required for such a a branch and release is
significantly greater than the effort needed to create a new release
from the head of the release branch).
Releases 5.0 and 5.1 used branch and release tags of the form:
gdb_N_M-YYYY-MM-DD-branchpoint
gdb_N_M-YYYY-MM-DD-branch
gdb_M_N-YYYY-MM-DD-release
Release 5.2 is trialing the branch and release tags:
gdb_N_M-YYYY-MM-DD-branchpoint
gdb_N_M-branch
gdb_M_N-YYYY-MM-DD-release
_Pragmatics: The branchpoint and release tags need to identify when
a branch and release are made. The branch tag, denoting the head of the
branch, does not have this criteria._
Branch Commit Policy
====================
The branch commit policy is pretty slack. GDB releases 5.0, 5.1 and
5.2 all used the below:
* The `gdb/MAINTAINERS' file still holds.
* Don't fix something on the branch unless/until it is also fixed in
the trunk. If this isn't possible, mentioning it in the
`gdb/PROBLEMS' file is better than committing a hack
* When considering a patch for the branch, suggested criteria
include: Does it fix a build? Does it fix the sequence `break
main; run' when debugging a static binary?
* The further a change is from the core of GDB, the less likely the
change will worry anyone (e.g., target specific code).
* Only post a proposal to change the core of GDB after you've sent
individual bribes to all the people listed in the `MAINTAINERS'
file ;-)
_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._
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 <gdb@sources.redhat.com>
* wait a week or so
* announce the change on GDB Announcement mailing list
<gdb-announce@sources.redhat.com>
* 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._
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:
* `texinfo/texinfo.tex'
* `config.guess' et. al. (see the top-level `MAINTAINERS' file)
* `etc/standards.texi', `etc/make-stds.texi'
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.
Review the bug data base
------------------------
Close anything obviously fixed.
Check all cross targets build
-----------------------------
The targets are listed in `gdb/MAINTAINERS'.
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 tagged 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
----------------------------------
Stabilize the branch
====================
Something goes here.
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._
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 opportunity to
check that things like your `NEWS' entries are correct or that other
changes actually work._
Release the tar ball
====================
This is where, unfortunately, 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 <gdb-announce@sources.redhat.com>
* 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).
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.
Post release
============
Remove any `OBSOLETE' code.
automatically generated by info2www version 1.2.2.9