[rfa/doc] Versions and Branches

[Andrew Cagney <ac131313@cygnus.com>]

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

Hello,

This is the revised version/branch section of gdbint.texinfo.  Looking 
beter?

Andrew

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

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

	* gdbint.texinfo (Releasing GDB): Add section ``Version
	identifiers'' and Branch Names''

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.67
diff -u -r1.67 gdbint.texinfo
--- gdbint.texinfo	2002/03/04 20:38:10	1.67
+++ gdbint.texinfo	2002/03/15 06:53:05
@@ -4822,6 +4822,106 @@
 @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-MM-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.minor} from of the previous release series
+but with @var{.90} appended.  As draft releases are drawn from the
+branch, the minor minor number (@var{.90}) is incremented.  Once the
+first release (@var{M.N}) has been made, the version prefix is updated
+to @var{M.N.0.90} (dot zero, dot ninety).  Follow on releases have an
+incremented minor minor version number (@var{.0}).
+
+Using @var{5.1} (previous) and @var{5.2} (current), the example below
+illustrates a typical sequence of version identifiers:
+
+@table @var
+@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 @var{5.2.0.91} have
+been omitted from the example.  Such release candidates are, typically,
+never made.
+@item
+For @var{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 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@. @var{5.1.0.1}) the conflict between that and a minor minor draft
+release identifier (e@.g@. @var{5.1.0.90}) is avoided.
+
+
+@subsection Branches
+
+@value{GDBN} draws a release series (@var{5.2}, @var{5.2.1}, @dots{})
+from a single release branch (@var{gdb_5_2-branch}).  Since minor minor
+minor releases (@var{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 @var{5.0} and @var{5.1} used branch and release tags of the
+form:
+
+@example
+gdb_N_M-YYYY-MM-DD-branchpoint
+gdb_N_M-YYYY-MM-DD-branch
+gdb_M_N-YYYY-MM-DD-release
+@end example
+
+Release @var{5.2} is trialing the branch and release tags:
+
+@example
+gdb_N_M-YYYY-MM-DD-branchpoint
+gdb_N_M-branch
+gdb_M_N-YYYY-MM-DD-release
+@end example
+
+@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 Obsolete any code
 
 Before anything else, poke the other developers (and around the source