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".
This commit is contained in:
Andrew Cagney
parent
7fa3d080a2
commit
d52fe014d1
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
@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:
|
||||
@value{GDBN}'s version is determined by the file
|
||||
@file{gdb/version.in} and takes one of the following forms:
|
||||
|
||||
@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
|
||||
@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
|
||||
|
||||
Notes:
|
||||
@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.
|
||||
|
||||
@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
|
||||
@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}.
|
||||
|
||||
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:
|
||||
|
||||
@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
|
||||
|
||||
@section Release Branches
|
||||
@cindex Release Branches
|
||||
|
||||
@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:
|
||||
|
||||
@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)}.
|
||||
|
||||
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.
|
||||
@section Experimental Branches
|
||||
@cindex experimental branches
|
||||
|
||||
@subsection Guidelines
|
||||
|
||||
@subsection Branches
|
||||
@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.
|
||||
|
||||
@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).
|
||||
The following are a set of guidelines for creating such branches:
|
||||
|
||||
Releases 5.0 and 5.1 used branch and release tags of the form:
|
||||
@table @emph
|
||||
|
||||
@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).
|
||||
|
||||
@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.
|
||||
|
||||
@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.}
|
||||
@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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue