[patch;rfa:doc] 5.2.50 on mainline

[Andrew Cagney <cagney at gnu dot org>]

Hello,

Ref: http://sources.redhat.com/ml/gdb/2004-08/msg00028.html

This patch implements the proposed change of GDB's mainline version 
number so that it includes dot-five-o (6.2.50).

This also adds a new chapter to the internal documentation that 
describes GDB's version/branch process (it pulls together some 
previously uncommitted changes and an old subsection of the branch process).

comments?

doco ok?

Andrew
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".

Index: ChangeLog
2004-09-21  Andrew Cagney  <cagney@gnu.org>

	* version.in: Bump to version 6.3.50.

Index: version.in
===================================================================
RCS file: /cvs/src/src/gdb/version.in,v
retrieving revision 1.1169
diff -p -c -r1.1169 version.in
*** version.in	21 Sep 2004 00:00:02 -0000	1.1169
--- version.in	21 Sep 2004 20:20:10 -0000
***************
*** 1 ****
! 2004-09-21-cvs
--- 1 ----
! 6.3.50_2004-09-21-cvs
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