2004-10-12 Andrew Cagney <cagney@gnu.org>

* gdbint.texinfo (Versions and Branches): New chapter. (Releasing GDB): Delete "Versions and Branches" section. (Top): Add "Versions and Branches".
author: Andrew Cagney <cagney@redhat.com> 2004-10-12 19:14:31 +0000
committer: Andrew Cagney <cagney@redhat.com> 2004-10-12 19:14:31 +0000
commit: d52fe014d1263631d8b6691ad87e9b8e44468265 (patch)
tree: 4b372e48b3636d57de29d082fb0cee1daf0d2120
parent: 7fa3d080a22840ecb8e69760ecd8ce41a36e03fc (diff)
download: gdb-d52fe014d1263631d8b6691ad87e9b8e44468265.zip
gdb-d52fe014d1263631d8b6691ad87e9b8e44468265.tar.gz
gdb-d52fe014d1263631d8b6691ad87e9b8e44468265.tar.bz2
2 files changed, 172 insertions, 76 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 9f80f02..c46594b 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,9 @@
+2004-10-12  Andrew Cagney  <cagney@gnu.org>
+
+	* gdbint.texinfo (Versions and Branches): New chapter.
+	(Releasing GDB): Delete "Versions and Branches" section.
+	(Top): Add "Versions and Branches".
+
 2004-10-08  Eli Zaretskii  <eliz@gnu.org>
 
 	* gdb.texinfo (Editing, History): Add cross-references to the
diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
index 38532d3..3c27769 100644
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -84,6 +84,7 @@ as the mechanisms that adapt @value{GDBN} to specific hosts and targets.
 * Support Libraries::
 * Coding::
 * Porting GDB::
+* Versions and Branches::
 * Releasing GDB::
 * Testsuite::
 * Hints::
@@ -5379,109 +5380,198 @@ target-dependent @file{.h} and @file{.c} files used for your
 configuration.
 @end itemize
 
-@node Releasing GDB
+@node Versions and Branches
+@chapter Versions and Branches
 
-@chapter Releasing @value{GDBN}
-@cindex making a new release of gdb
+@section Versions
 
-@section Versions and Branches
+@value{GDBN}'s version is determined by the file
+@file{gdb/version.in} and takes one of the following forms:
 
-@subsection Version Identifiers
+@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 release 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 version is determined by the file @file{gdb/version.in}.
+@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 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 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.  Once the first
+release (@var{major}.@var{minor}) has been made, the version prefix is
+updated to @var{major}.@var{minor}.0.90.  Follow on releases have an
+incremented @var{patchlevel}.
 
-@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).
+If the previous @value{GDBN} version is 6.1 and the current version is
+6.2, then, substituting 6 for @var{major} and 1 or 2 for @var{minor},
+here's an illustration of a typical sequence:
 
-Using 5.1 (previous) and 5.2 (current), the example below illustrates a
-typical sequence of version identifiers:
+@smallexample
+     <HEAD>
+        |
+6.1.50_2002-03-02-cvs
+        |
+        +---------------------------.
+        |                    <gdb_6_2-branch>
+        |                           |
+6.2.50_2002-03-03-cvs        6.1.90 (draft #1)
+        |                           |
+6.2.50_2002-03-04-cvs        6.1.90_2002-03-04-cvs
+        |                           |
+6.2.50_2002-03-05-cvs        6.1.91 (draft #2)
+        |                           |
+6.2.50_2002-03-06-cvs        6.1.91_2002-03-06-cvs
+        |                           |
+6.2.50_2002-03-07-cvs        6.2 (release)
+        |                          |
+6.2.50_2002-03-08-cvs        6.2.0.90_2002-03-08-cvs
+        |                          |
+6.2.50_2002-03-09-cvs        6.2.1 (update)
+        |                           |
+6.2.50_2002-03-10-cvs         <branch closed>
+        |
+6.2.50_2002-03-11-cvs
+        |
+        +---------------------------.
+        |                     <gdb_6_3-branch>
+        |                           |
+6.3.50_2002-03-12-cvs        6.2.90 (draft #1)
+        |                           |
+@end smallexample
 
-@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
+@section Release Branches
+@cindex Release Branches
 
-Notes:
+@value{GDBN} draws a release series (6.2, 6.2.1, @dots{}) from a
+single release branch, and identifies that branch using the @sc{cvs}
+branch tags:
 
-@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
+@smallexample
+gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-branchpoint
+gdb_@var{major}_@var{minor}-branch
+gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-release
+@end smallexample
+
+@emph{Pragmatics: To help identify the date at which a branch or
+release is made, both the branchpoint and release tags include the
+date that they are cut (@var{YYYY}@var{MM}@var{DD}) in the tag.  The
+branch tag, denoting the head of the branch, does not need this.}
+
+@section Vendor Branches
+@cindex 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).
+its version identifer).  E.g., @samp{6.2widgit2}, or @samp{6.2 (Widgit
+Inc Patch 2)}.
+
+@section Experimental Branches
+@cindex experimental branches
 
-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 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.
 
-@subsection Branches
+The following are a set of guidelines for creating such branches:
+
+@table @emph
 
-@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).
+@item a branch has 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).
 
-Releases 5.0 and 5.1 used branch and release tags of the form:
+@item all commits are posted
+All changes committed to a branch shall also be posted to
+@email{gdb-patches@@sources.redhat.com, the @value{GDBN} patches
+mailing list}.  While commentary on such changes are encouraged, people
+should remember that the changes only apply to a branch.
 
+@item all commits are covered by an assignment
+This ensures that all changes belong to the Free Software Foundation,
+and avoids the possibility that the branch may become contaminated.
+
+@item a branch is focused
+A focused branch has a single objective or goal, and does not contain
+unnecessary or irrelevant changes.  Cleanups, where identified, being
+be pushed into the mainline as soon as possible.
+
+@item a branch tracks 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).  @xref{Tags}.
+
+@item a branch shall be branded using @file{version.in}
+The file @file{gdb/version.in} shall be modified so that it identifies
+the branch @var{owner} and branch @var{name}, e.g.,
+@samp{6.2.50_20030303_owner_name} or @samp{6.2 (Owner Name)}.
+
+@end table
+
+@subsection Tags
+@anchor{Tags}
+
+To simplify the identification of @value{GDBN} branches, the following
+branch tagging 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: @anchor{experimental branch tags}
 @smallexample
-gdb_N_M-YYYY-MM-DD-branchpoint
-gdb_N_M-YYYY-MM-DD-branch
-gdb_M_N-YYYY-MM-DD-release
+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
 
-Release 5.2 is trialing the branch and release tags:
-
+@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
-gdb_N_M-YYYY-MM-DD-branchpoint
-gdb_N_M-branch
-gdb_M_N-YYYY-MM-DD-release
+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
 
-@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.}
+@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
author	Andrew Cagney <cagney@redhat.com>	2004-10-12 19:14:31 +0000
committer	Andrew Cagney <cagney@redhat.com>	2004-10-12 19:14:31 +0000
commit	d52fe014d1263631d8b6691ad87e9b8e44468265 (patch)
tree	4b372e48b3636d57de29d082fb0cee1daf0d2120
parent	7fa3d080a22840ecb8e69760ecd8ce41a36e03fc (diff)
download	gdb-d52fe014d1263631d8b6691ad87e9b8e44468265.zip gdb-d52fe014d1263631d8b6691ad87e9b8e44468265.tar.gz gdb-d52fe014d1263631d8b6691ad87e9b8e44468265.tar.bz2