[wip] How to release section

[wip] How to release section

[Andrew Cagney]

[-- Attachment #1: Type: text/plain, Size: 137 bytes --]

Hello,

Attached is a (very obviously) work in progress patch for the internals 
manual going through how to release GDB.

enjoy,
Andrew

[-- Attachment #2: diffs --]
[-- Type: text/plain, Size: 4410 bytes --]

2002-01-15  Andrew Cagney  <ac131313@redhat.com>

	* gdbint.texinfo (Releasing GDB): New chapter.

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.53
diff -p -r1.53 gdbint.texinfo
*** gdbint.texinfo	2002/01/15 01:29:24	1.53
--- gdbint.texinfo	2002/01/15 05:15:43
*************** as the mechanisms that adapt @value{GDBN
*** 93,98 ****
--- 93,99 ----
  * Support Libraries::
  * Coding::
  * Porting GDB::
+ * Releasing GDB::
  * Testsuite::
  * Hints::
  * Index::
*************** distribution, generate @file{gdb-all.tex
*** 4820,4825 ****
--- 4821,4973 ----
  files @file{gdb.info*} in the distribution.  Note the plural;
  @code{makeinfo} will split the document into one overall file and five
  or so included files.
+ 
+ @node Releasing GDB
+ 
+ @chapter Releasing @value{GDBN}
+ @cindex making a new release of gdb
+ 
+ @section Before the branch
+ 
+ Mark as OBSOLETE any uninteresting targets or code files.  This has a
+ number of steps and is slow - mainly to ensure that people have had a
+ reasonable chance to respond.  Remember, everything on the internet
+ takes a week.
+ 
+ @itemize @bullet
+ @item
+ announce the change on gdb@
+ @item
+ wait a week
+ @item
+ announce the change on gdb-announce@
+ @item
+ wait a week or so
+ @item
+ post / commit the change
+ @end itemize
+ 
+ Organize the schedule.
+ 
+ @itemize @bullet
+ @item
+ announce it
+ @item
+ wait a week
+ @item
+ announce branch date
+ @item
+ wait a week
+ @item
+ you want to encourage people to sanity check their build as you really
+ don't want to be contending with configury problems as getting them
+ committed is complicated.
+ @item
+ Cut the branch
+ @item
+ wait a week
+ @item
+ start enjoying all the fun
+ @end itemize
+ 
+ As an aside, the branch tag name is probably regrettable vis:
+ gdb_N_M-YYYY-MM-DD-@{branch,branchpoint@}.
+ 
+ 
+ @section Building a Release
+ 
+ @subheading Establish a few defaults.
+ 
+ @example
+ $  b=gdb_5_1_0_1-2002-01-03-branch
+ $  v=5.1.0.1
+ $  cd /sourceware/snapshot-tmp/gdbadmin-tmp/$b
+ $  which autoconf
+ /home/gdbadmin/bin/autoconf
+ @end example
+ 
+ NB: Check the autoconf version carefully.  You want to be using
+ gdbadmin's version (which is really the version taken from the binutils
+ snapshot).  SWARE may have a different version installed.
+ 
+ @subheading Check out the relevant modules:
+ 
+ @example
+ $  for m in gdb insight dejagnu; do
+ ( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m )
+ done
+ @end example
+ 
+ NB: The reading of .cvsrc is disabled (-f) so that there isn't any
+ confusion between what is written here and what CVS really does.
+ 
+ @subheading Update the file gdb/version.in where applicable.
+ 
+ @example
+ $  for m in gdb insight; do echo $v > $m/src/gdb/version.in ; done
+ @end example
+ 
+ @subheading Mutter something about creating a ChangeLog entry. (both trunk and branch).
+ 
+ @example
+ $  emacs gdb/src/gdb/version.in
+ c-x 4 a
+ Bump version to 5.1.0.1.
+ c-x c-s c-x c-c
+ ditto for insight/src/gdb/version.in
+ @end example
+ 
+ @subheading Mutter something about updating README
+ 
+ For dejagnu, edit ``dejagnu/src/dejagnu/configure.in'' and set it to
+ gdb-$v and then regenerate configure.  Mention this in the dejagnu
+ ChangeLog.
+ 
+ @example
+ $  emacs dejagnu/src/dejagnu/configure.in
+ ...
+ c-x 4 a
+ Bump version to 5.1.0.1.
+ * configure: Re-generate.
+ c-x c-s c-x c-c
+ $  ( cd dejagnu/src/dejagnu && autoconf )
+ @end example
+ 
+ @subheading Build the snapshot:
+ 
+ @example
+ $  for m in gdb insight dejagnu; do
+ ( cd $m/src && gmake -f Makefile.in $m.tar.bz2 )
+ done
+ @end example
+ 
+ @subheading Do another CVS update to see what the damage is.
+ 
+ @example
+ $  ( cd gdb/src && cvs -q update )
+ @end example
+ 
+ You're looking for files that have mysteriously disappeared as the
+ distclean has the habit of deleting files it shouldn't.
+ 
+ @subheading Copy all the .bz2 files to the ftp directory:
+ 
+ @example
+ cp */src/*.bz2 ~ftp/.....
+ @end example
+ 
+ @subheading Something about gzip'ing them.
+ 
+ @subheading Something about web pages?
+ 
+ @subheading Something about documentation?
+ 
+ @subheading Something about committing _all_ the generated files.
+ 
+ @section After the release
+ 
+ Remove any OBSOLETE code.
+ 
  
  @node Testsuite
  

Re: [wip] How to release section

[Eli Zaretskii]

On Tue, 15 Jan 2002, Andrew Cagney wrote:

> Attached is a (very obviously) work in progress patch for the internals 
> manual going through how to release GDB.

Approved, with the following comments:

> + Mark as OBSOLETE any uninteresting targets or code files.  This has a
> + number of steps and is slow - mainly to ensure that people have had a
                               ^^^
Please use "---" when you want a dash.  (The Texinfo manual explains
why--it's a TeX peculiarity.)

> + @item
> + announce the change on gdb@

You need to double every `@' in Texinfo.  (Actually, I'd suggest to
use a full address here, like this:

  announce the change on @email{gdb@@sources.redhat.com, GDB mailing list}

> + announce the change on gdb-announce@

Same here.

> + announce branch date
> + @item
> + wait a week
> + @item
> + you want to encourage people to sanity check their build as you really
> + don't want to be contending with configury problems as getting them
> + committed is complicated.

This last item looks like a footnote, and its style is different from
the other items.  Perhaps it should be a @footnote.

> + As an aside, the branch tag name is probably regrettable vis:
> + gdb_N_M-YYYY-MM-DD-@{branch,branchpoint@}.

This should be in @file, and again double the `@'.

> + NB: Check the autoconf version carefully.  You want to be using
> + gdbadmin's version (which is really the version taken from the binutils

`gdbadmin' is a command, so should be in @code.

> + NB: The reading of .cvsrc is disabled (-f) so that there isn't any

`.cvsrc' should be in @file.

> + @subheading Update the file gdb/version.in where applicable.

`gdb/version.in' should be in @file.

> + @subheading Mutter something about creating a ChangeLog entry. (both trunk and branch).

`ChangeLog' should be in @file.

> + @subheading Mutter something about updating README

`README' should be in @file.

> + For dejagnu, edit ``dejagnu/src/dejagnu/configure.in'' and set it to

`dejagnu/src/dejagnu/configure.in' should be in @file.

> + @subheading Do another CVS update to see what the damage is.

"CVS update" should be in @kbd (it's something you type at the
keyboard).

> + You're looking for files that have mysteriously disappeared as the
> + distclean has the habit of deleting files it shouldn't.

`distclean' should be in @samp or @kbd.

> + @subheading Copy all the .bz2 files to the ftp directory:

`.bz2' should be in @file.

Re: [wip] How to release section

[Andrew Cagney]

[-- Attachment #1: Type: text/plain, Size: 2904 bytes --]


> Approved, with the following comments:


I'm taking a slight liberty by checking in the attached revision.  It 
fixed most of the problems and I'll fix the rest in the next round in a 
week or so.  (But with the kdb->kbd typo fixed).


>> + Mark as OBSOLETE any uninteresting targets or code files.  This has a
>> + number of steps and is slow - mainly to ensure that people have had a
> 
> ^^^
> Please use "---" when you want a dash.  (The Texinfo manual explains
> why--it's a TeX peculiarity.)


Yes, I missed that.


> You need to double every `@' in Texinfo.  (Actually, I'd suggest to
> use a full address here, like this:
> 
>   announce the change on @email{gdb@@sources.redhat.com, GDB mailing list}


Done.


>> + announce the change on gdb-announce@
> 
> 
> Same here.


Done.


>> + announce branch date
>> + @item
>> + wait a week
>> + @item
>> + you want to encourage people to sanity check their build as you really
>> + don't want to be contending with configury problems as getting them
>> + committed is complicated.
> 
> 
> This last item looks like a footnote, and its style is different from
> the other items.  Perhaps it should be a @footnote.


Agreed.  I rearanged the section.


>> + As an aside, the branch tag name is probably regrettable vis:
>> + gdb_N_M-YYYY-MM-DD-@{branch,branchpoint@}.
> 
> 
> This should be in @file, and again double the `@'.


Done.  Not sure about the @ here.  I'm trying to get

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

in the final doco.


>> + NB: Check the autoconf version carefully.  You want to be using
>> + gdbadmin's version (which is really the version taken from the binutils
> 
> 
> `gdbadmin' is a command, so should be in @code.


It is an account.  @code or @var or @file or???  I put it in an @file 
for the moment.


>> + NB: The reading of .cvsrc is disabled (-f) so that there isn't any
> 
> 
> `.cvsrc' should be in @file.


I also made it @code{-f}.


>> + @subheading Update the file gdb/version.in where applicable.
> 
> 
> `gdb/version.in' should be in @file.
> 
> 
>> + @subheading Mutter something about creating a ChangeLog entry. (both trunk and branch).
> 
> 
> `ChangeLog' should be in @file.
> 
> 
>> + @subheading Mutter something about updating README
> 
> 
> `README' should be in @file.
> 
> 
>> + For dejagnu, edit ``dejagnu/src/dejagnu/configure.in'' and set it to
> 
> 
> `dejagnu/src/dejagnu/configure.in' should be in @file.


Ok.


>> + @subheading Do another CVS update to see what the damage is.
> 
> 
> "CVS update" should be in @kbd (it's something you type at the
> keyboard).


Done.


>> + You're looking for files that have mysteriously disappeared as the
>> + distclean has the habit of deleting files it shouldn't.
> 
> 
> `distclean' should be in @samp or @kbd.



Done.


>> + @subheading Copy all the .bz2 files to the ftp directory:
> 
> 
> `.bz2' should be in @file.


Done.


Andrew




[-- Attachment #2: diffs --]
[-- Type: text/plain, Size: 5554 bytes --]

2002-01-15  Andrew Cagney  <ac131313@redhat.com>

	* gdbint.texinfo (Releasing GDB): New chapter.

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.53
diff -p -r1.53 gdbint.texinfo
*** gdbint.texinfo	2002/01/15 01:29:24	1.53
--- gdbint.texinfo	2002/01/15 18:58:24
*************** as the mechanisms that adapt @value{GDBN
*** 93,98 ****
--- 93,99 ----
  * Support Libraries::
  * Coding::
  * Porting GDB::
+ * Releasing GDB::
  * Testsuite::
  * Hints::
  * Index::
*************** distribution, generate @file{gdb-all.tex
*** 4820,4825 ****
--- 4821,5010 ----
  files @file{gdb.info*} in the distribution.  Note the plural;
  @code{makeinfo} will split the document into one overall file and five
  or so included files.
+ 
+ @node Releasing GDB
+ 
+ @chapter Releasing @value{GDBN}
+ @cindex making a new release of gdb
+ 
+ @section 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 @value{GDBN} from even
+ building.  If you can't get the problem fixed, document it in the
+ @file{PROBLEMS} file.
+ 
+ @subheading Obsolete any code
+ 
+ Mark as @kbd{OBSOLETE} any uninteresting targets or code files.  This
+ has a number of steps and is slow --- mainly to ensure that people have
+ had a reasonable chance to respond.  Remember, everything on the
+ internet takes a week.
+ 
+ @itemize @bullet
+ @item
+ announce the change on @email{gdb@@sources.redhat.com, GDB mailing list}
+ @item
+ wait a week
+ @item
+ announce the change on @email{gdb-announce@@sources.redhat.com, GDB
+ Announcement mailing list}
+ @item
+ wait a week or so
+ @item
+ post / commit the change
+ @end itemize
+ 
+ @subheading Refresh any imported files.
+ 
+ A number of files are taken from external repositories.  They include:
+ 
+ @itemize @bullet
+ @item
+ @file{texinfo/texinfo.tex}
+ @item
+ @file{config.guess} et.@: al.@: 
+ @end itemize
+ 
+ and should be refreshed.
+ 
+ @subheading 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.
+ 
+ @itemize @bullet
+ @item
+ announce it
+ @item
+ wait a week
+ @item
+ announce branch date
+ @item
+ wait a week
+ @item
+ Cut the branch
+ @item
+ wait a week
+ @item
+ start enjoying all the fun
+ @end itemize
+ 
+ As an aside, the branch tag name is probably regrettable vis:
+ @file{gdb_N_M-YYYY-MM-DD-@{branch,branchpoint@}}.
+ 
+ 
+ @section Building a Release
+ 
+ @subheading Establish a few defaults.
+ 
+ @example
+ $  b=gdb_5_1_0_1-2002-01-03-branch
+ $  v=5.1.0.1
+ $  cd /sourceware/snapshot-tmp/gdbadmin-tmp/$b
+ $  which autoconf
+ /home/gdbadmin/bin/autoconf
+ @end example
+ 
+ NB: Check the autoconf version carefully.  You want to be using
+ @file{gdbadmin}'s version (which is really the version taken from the
+ binutils snapshot).  SWARE may have a different version installed.
+ 
+ @subheading Check out the relevant modules:
+ 
+ @example
+ $  for m in gdb insight dejagnu; do
+ ( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m )
+ done
+ @end example
+ 
+ NB: The reading of @file{.cvsrc} is disabled (@file{-f}) so that there
+ isn't any confusion between what is written here and what CVS really
+ does.
+ 
+ @subheading Update the file @file{gdb/version.in} where applicable.
+ 
+ @example
+ $ for m in gdb insight; do echo $v > $m/src/gdb/version.in ; done
+ @end example
+ 
+ 
+ @subheading Mutter something about creating a @file{ChangeLog} entry. (both trunk and branch).
+ 
+ @example
+ $  emacs gdb/src/gdb/version.in
+ c-x 4 a
+ Bump version to 5.1.0.1.
+ c-x c-s c-x c-c
+ @end example
+ 
+ ditto for @file{insight/src/gdb/version.in}
+ 
+ @subheading Mutter something about updating @file{README}
+ 
+ For dejagnu, edit @file{dejagnu/src/dejagnu/configure.in} and set it to
+ gdb-$v and then regenerate configure.  Mention this in the dejagnu
+ @file{ChangeLog}.
+ 
+ @example
+ $  emacs dejagnu/src/dejagnu/configure.in
+ ...
+ c-x 4 a
+ Bump version to 5.1.0.1.
+ * configure: Re-generate.
+ c-x c-s c-x c-c
+ $  ( cd dejagnu/src/dejagnu && autoconf )
+ @end example
+ 
+ @subheading Build the snapshot:
+ 
+ @example
+ $  for m in gdb insight dejagnu; do
+ ( cd $m/src && gmake -f Makefile.in $m.tar.bz2 )
+ done
+ @end example
+ 
+ @subheading Do another @kpd{CVS update} to see what the damage is.
+ 
+ @example
+ $ ( cd gdb/src && cvs -q update )
+ @end example
+ 
+ You're looking for files that have mysteriously disappeared as the
+ @kbd{distclean} has the habit of deleting files it shouldn't.  Watch out
+ for the @file{version.in} update cronjob.
+ 
+ @subheading Copy all the @file{.bz2} files to the ftp directory:
+ 
+ @example
+ cp */src/*.bz2 ~ftp/.....
+ @end example
+ 
+ @subheading Something about @kbd{gzip}'ing them.
+ 
+ @subheading Something about web pages?
+ 
+ @subheading Something about documentation?
+ 
+ @subheading Cleanup the release tree
+ 
+ In particular you'll need to:
+ 
+ @itemize @bullet
+ @item
+ Commit the changes to @file{ChangeLog} and @file{version.in}
+ @item
+ Tag the repository.
+ @end itemize
+ 
+ 
+ @section After the release
+ 
+ Remove any @kbd{OBSOLETE} code.
+ 
  
  @node Testsuite
  

Re: [wip] How to release section

[Eli Zaretskii]

On Tue, 15 Jan 2002, Andrew Cagney wrote:

> >> + As an aside, the branch tag name is probably regrettable vis:
> >> + gdb_N_M-YYYY-MM-DD-@{branch,branchpoint@}.
> > 
> > This should be in @file, and again double the `@'.
> 
> Done.  Not sure about the @ here.  I'm trying to get
> 
> 	gdb_N_M-YYYY-MM-DD-{branch,branchpoint}
> 
> in the final doco.

Oops, my bad: I missed the fact that there are braces there.  @{ and @} 
is correct, sorry.

> > `gdbadmin' is a command, so should be in @code.
> 
> 
> It is an account.  @code or @var or @file or???  I put it in an @file 
> for the moment.

If it's an account, I think @code is the right one.  @samp and @file are 
also okay, but @var is certainly wrong (it will be UPCASED in Info and 
italics in the printed maual--not what you want).