From d52fe014d1263631d8b6691ad87e9b8e44468265 Mon Sep 17 00:00:00 2001 From: Andrew Cagney Date: Tue, 12 Oct 2004 19:14:31 +0000 Subject: [PATCH] 2004-10-12 Andrew Cagney * gdbint.texinfo (Versions and Branches): New chapter. (Releasing GDB): Delete "Versions and Branches" section. (Top): Add "Versions and Branches". --- gdb/doc/ChangeLog | 6 + gdb/doc/gdbint.texinfo | 242 ++++++++++++++++++++++++++++------------- 2 files changed, 172 insertions(+), 76 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 9f80f02c9b7..c46594bddb9 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,9 @@ +2004-10-12 Andrew Cagney + + * gdbint.texinfo (Versions and Branches): New chapter. + (Releasing GDB): Delete "Versions and Branches" section. + (Top): Add "Versions and Branches". + 2004-10-08 Eli Zaretskii * gdb.texinfo (Editing, History): Add cross-references to the diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 38532d3f0ca..3c27769b53e 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 + + | +6.1.50_2002-03-02-cvs + | + +---------------------------. + | + | | +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 + | +6.2.50_2002-03-11-cvs + | + +---------------------------. + | + | | +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 -- 2.30.2