Re: [patch;rfa:doc] 5.2.50 on mainline

[Andrew Cagney <cagney@gnu.org>]

> Index: doc/ChangeLog
> 2004-09-21  Andrew Cagney  <cagney@gnu.org>
> 
> 	* gdbint.texinfo (Versions and Branches): New chapter.
> 	(Releasing GDB): Delete "Versions and Branches" section.
> 	(Top): Add "Versions and Branches".

Ping (but Joel made some comments).

> Index: ChangeLog
> 2004-09-21  Andrew Cagney  <cagney@gnu.org>
> 
> 	* version.in: Bump to version 6.3.50.
> 

I've checked this in (but as 6.2.50 :-).

Andrew

> Index: doc/gdbint.texinfo
> ===================================================================
> RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
> retrieving revision 1.224
> diff -p -c -r1.224 gdbint.texinfo
> *** doc/gdbint.texinfo	12 Sep 2004 15:20:49 -0000	1.224
> --- doc/gdbint.texinfo	21 Sep 2004 20:20:12 -0000
> *************** as the mechanisms that adapt @value{GDBN
> *** 84,89 ****
> --- 84,90 ----
>   * Support Libraries::
>   * Coding::
>   * Porting GDB::
> + * Versions and Branches::
>   * Releasing GDB::
>   * Testsuite::
>   * Hints::
> *************** target-dependent @file{.h} and @file{.c}
> *** 5368,5476 ****
>   configuration.
>   @end itemize
>   
> ! @node Releasing GDB
>   
> ! @chapter Releasing @value{GDBN}
> ! @cindex making a new release of gdb
>   
> ! @section Versions and Branches
>   
> ! @subsection Version Identifiers
>   
> ! @value{GDBN}'s version is determined by the file @file{gdb/version.in}.
>   
> ! @value{GDBN}'s mainline uses ISO dates to differentiate between
> ! versions.  The CVS repository uses @var{YYYY}-@var{MM}-@var{DD}-cvs
> ! while the corresponding snapshot uses @var{YYYYMMDD}.
> ! 
> ! @value{GDBN}'s release branch uses a slightly more complicated scheme.
> ! When the branch is first cut, the mainline version identifier is
> ! prefixed with the @var{major}.@var{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 (@var{M}.@var{N}) has been made, the version prefix is updated
> ! to @var{M}.@var{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:
>   
> ! @table @asis
> ! @item 5.1.1
> ! final release from previous branch
> ! @item 2002-03-03-cvs
> ! main-line the day the branch is cut
> ! @item 5.1.90-2002-03-03-cvs
> ! corresponding branch version
> ! @item 5.1.91
> ! first draft release candidate
> ! @item 5.1.91-2002-03-17-cvs
> ! updated branch version
> ! @item 5.1.92
> ! second draft release candidate
> ! @item 5.1.92-2002-03-31-cvs
> ! updated branch version
> ! @item 5.1.93
> ! final release candidate (see below)
> ! @item 5.2
> ! official release
> ! @item 5.2.0.90-2002-04-07-cvs
> ! updated CVS branch version
> ! @item 5.2.1
> ! second official release
> ! @end table
>   
> ! Notes:
>   
> ! @itemize @bullet
> ! @item
> ! 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.
> ! @item
> ! For 5.1.93 the bziped tar ball @file{gdb-5.1.93.tar.bz2} is just the
> ! official @file{gdb-5.2.tar} renamed and compressed.
> ! @end itemize
>   
>   To avoid version conflicts, vendors are expected to modify the file
>   @file{gdb/version.in} to include a vendor unique alphabetic identifier
>   (an official @value{GDBN} release never uses alphabetic characters in
> ! its version identifer).
>   
> ! Since @value{GDBN} 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.
>   
>   
> ! @subsection Branches
>   
> ! @value{GDBN} draws a release series (5.2, 5.2.1, @dots{}) 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:
>   
> ! @smallexample
> ! gdb_N_M-YYYY-MM-DD-branchpoint
> ! gdb_N_M-YYYY-MM-DD-branch
> ! gdb_M_N-YYYY-MM-DD-release
> ! @end smallexample
>   
> ! Release 5.2 is trialing the branch and release tags:
>   
> ! @smallexample
> ! gdb_N_M-YYYY-MM-DD-branchpoint
> ! gdb_N_M-branch
> ! gdb_M_N-YYYY-MM-DD-release
>   @end smallexample
>   
> ! @emph{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.}
>   
>   
>   @section Branch Commit Policy
>   
> --- 5369,5566 ----
>   configuration.
>   @end itemize
>   
> ! @node Versions and Branches
> ! @chapter Versions and Branches
>   
> ! @section Versions
>   
> ! @value{GDBN}'s version is determined by the file
> ! @file{gdb/version.in} and takes one of the following forms:
>   
> ! @table @asis
> ! @item @var{major}.@var{minor}
> ! @itemx @var{major}.@var{minor}.@var{patchlevel}
> ! an official release (e.g., 6.0 or 6.0.1).
> ! @item @var{major}.@var{minor}.@var{patchlevel}_@var{YYYY}@var{MM}@var{DD}
> ! a snapshot (e.g., 6.0.50_20020630).
> ! @item @var{major}.@var{minor}.@var{patchlevel}_@var{YYYY}-@var{MM}-@var{DD}-cvs
> ! a @sc{cvs} check out (e.g., 6.0.90_2004-02-30-cvs).
> ! @item @var{major}.@var{minor}.@var{patchlevel}_@var{YYYY}@var{MM}@var{DD} (@var{vendor})
> ! a vendor specific relese of @value{GDBN}, that while based on
> ! @var{major}.@var{minor}.@var{patchlevel}_@var{YYYY}@var{MM}@var{DD},
> ! may contain additional changes
> ! @end table
>   
> ! @value{GDBN}'s mainline uses the @var{major} and @var{minor} version
> ! numbers from the most recent release branch, with a @var{patchlevel}
> ! of 50.  As each new release branch is created, the mainline
> ! @var{major} and @var{minor} version numbers are accordingly updated.
> ! 
> ! @value{GDBN}'s release branch uses a similar, but slightly more
> ! complicated scheme.  When the branch is first cut, the mainline's
> ! @var{patchlevel} is changed to .90.  As draft releases are
> ! drawn from the branch, the @var{patchlevel} is incremented is
> ! incremented.  Once the first release (@var{M}.@var{N}) has been made,
> ! the version prefix is updated to @var{major}.@var{minor}.0.90.  Follow
> ! on releases have an incremented @var{patchlevel}.
> ! 
> ! Using 5.1 (previous) and 5.2 (current), the example below illustrates
> ! a typical sequence:
> ! 
> ! @smallexample
> !       <mainline>
> !           |
> !   5.1.50_2002-03-03-cvs
> !           |
> !           +--------------------------.
> !        <branch>                  <mainline>
> !           |                          |
> !    5.1.90 (draft #1)         5.2.50_2002-03-03-cvs
> !           |                          |
> !   5.1.90_2002-03-03-cvs      5.2.50_2002-03-04-cvs
> !           |                          |
> !    5.1.91 (draft #2)         5.2.50_2002-03-05-cvs
> !           |                          |
> !   5.1.91_2002-03-05-cvs      5.2.50_2002-03-06-cvs
> !           |                          |
> !      5.2 (release)           5.2.50_2002-03-06-cvs
> !           |                          |
> !   5.2.0.90_2002-03-07-cvs    5.2.50_2002-03-07-cvs
> !           |                          |
> !     5.2.1 (update)           5.2.50_2002-03-08-cvs
> !                                      |
> !                                      +----------- -  -
> !                                   <branch>
> !                                      |
> !                               5.2.90 (draft #1)
> ! @end smallexample
>   
> ! Since @value{GDBN} does not make minor minor minor releases (e.g.,
> ! 5.1.0.1) the conflict between that and a patch level draft release
> ! identifier (e.g., 5.1.0.90) is avoided.
>   
> ! @section Release Branches
> ! @cindex Release Branches
>   
> ! @value{GDBN} draws a release series (5.2, 5.2.1, @dots{}) 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 patchlevel release from the head of the release branch).
>   
> ! @value{GDBN} uses the following release branch tags:
>   
> ! @smallexample
> ! gdb_N_M-YYYY-MM-DD-branchpoint
> ! gdb_N_M-branch
> ! gdb_M_N-YYYY-MM-DD-release
> ! @end smallexample
> ! 
> ! @emph{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.}
> ! 
> ! @section Vendor Branches
>   
>   To avoid version conflicts, vendors are expected to modify the file
>   @file{gdb/version.in} to include a vendor unique alphabetic identifier
>   (an official @value{GDBN} release never uses alphabetic characters in
> ! its version identifer).  E.g., @samp{5.2widgit2}, or @samp{5.2 (Widgit
> ! Inc Patch 2)}.
>   
> ! @section Experimental Branches
> ! @cindex branches
>   
> + @subsection Guidelines
>   
> ! @value{GDBN} permits the creation of branches, cut from the @sc{cvs}
> ! repository, for experimental development.  Branches make it possible
> ! for developers to share preliminary work, and maintainers to examine
> ! significant new developments.
>   
> ! The following are a set of guidelines for creating such branches:
>   
> ! @table @emph
>   
> ! @item a branch shall have an owner
> ! The owner can set further policy for a branch, but may not change the
> ! ground rules.  In particular, they can set a policy for commits (be it
> ! adding more reviewers or deciding who can commit).
> ! 
> ! @item all commits shall be posted
> ! All changes committed to a branch shall also be posted to the
> ! @email{gdb-patches@@sources.redhat.com, the @value{GDBN} patches}
> ! mailing list.  While commentary on such chages are encouraged, people
> ! should remember that the changes only apply to a branch.
> ! 
> ! @item all commits shall be covered by an assignment
> ! This saves @value{GDBN} from the situation where a branch might become
> ! contaminated.
> ! 
> ! @item a branch shall to be focused
> ! A de-focused branch invariably generates lint (unnecessary and
> ! irelevant change).  Cleanups, where identified, should be pushed into
> ! the mainline as soon as possible
> ! 
> ! @item a branch shall track mainline.
> ! This keeps the level of divergence under control.  It also keeps the
> ! pressure on developers to push cleanups and other stuff into the
> ! mainline.
> ! 
> ! @item a branch shall contain the entire @value{GDBN} module
> ! The @value{GDBN} module @code{gdb} should be specified when creating a
> ! branch (branches of individual files should be avoided).
> ! 
> ! @item a branch shall be branded using @file{version.in}
> ! The file @file{gdb/version.in} shall be modified so that it identifes
> ! the branch @var{owner} and branch @var{name}, e.g.,
> ! @samp{5.2.50_20030303_owner_name} or @samp{5.2 (Owner Name)}.
>   
> ! @end table
>   
> ! @subsection Tags
> ! 
> ! To simplify the identification of @value{GDBN} branches, the following
> ! branch taging convention is strongly recommended:
> ! 
> ! @table @code
> ! 
> ! @item @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint
> ! @itemx @var{owner}_@var{name}-@var{YYYYMMDD}-branch
> ! The branch point and corresponding branch tag.  @var{YYYYMMDD} is the
> ! date that the branch was created.  A branch is created using the
> ! sequence:
> ! @smallexample
> ! cvs rtag @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint gdb
> ! cvs rtag -b -r @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint \
> !    @var{owner}_@var{name}-@var{YYYYMMDD}-branch gdb
> ! @end smallexample
> ! 
> ! @item @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint
> ! The tagged point, on the mainline, that was used when merging the branch
> ! on @var{yyyymmdd}.  To merge in all changes since the branch was cut,
> ! use a command sequence like:
> ! @smallexample
> ! cvs rtag @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint gdb
> ! cvs update \
> !    -j@var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint
> !    -j@var{owner}_@var{name}-@var{yyyymmdd}-mergepoint
>   @end smallexample
> + @noindent
> + Similar sequences can be used to just merge in changes since the last
> + merge.
>   
> ! @end table
>   
> + @noindent
> + For further information on @sc{cvs}, see
> + @uref{http://www.gnu.org/software/cvs/, Concurrent Versions System}.
> +  
> + @node Releasing GDB
> + 
> + @chapter Releasing @value{GDBN}
> + @cindex making a new release of gdb
>   
>   @section Branch Commit Policy
>