["patch"/doc] GDB version and branch names

[Andrew Cagney <ac131313 at cygnus dot com>]

Hello, below is an attemt at documenting the GDB branch and version 
policies.  Comments wanted.  If you think the rationale for something is 
unclear, please point it out.

enjoy,
Andrew

@section Version and branch names

@subsection Versions

@value{GDBN}'s version is determined by the file @file{gdb/version.in}.
@value{GDBN} never uses letters in its version identifier, letters being
reserved for vendor customised @value{GDBN} releases.  Conversely, a
vendor customised @value{GDBN} release is expected to modify the version
identifier so that it includes letters (and digits).

@value{GDBN}'s mainline uses only dates to differentiate between
versions.  The CVS repository uses @file{YYYY-MM-DD-cvs} while
corresponding snapshots use @file{YYYYMMDD}.

To avoid confusion between the main-line, @value{GDBN}'s release branches
use a more complex version naming scheme.  The schema assumes that a
series of releases, starting with a major.minor and possibly followed by a
number of major.minor.minor releases are all to be drawn from a single
branch.

When a release branch is first cut, the version identifier is updated to
include a prefix constructed from the previous release serieuses
major.minor (@file{m.n}) identification with a @file{.90} suffix
appended.  Consequently, CVS versions are identified with
@file{m.n.90-YYYY-MM-DD-cvs} and snapshots are identified with
@file{m.n.90_YYYYMMDD}.  As draft releases are drawn from the branch,
the minor minor number (@file{.90}) is incremented.

Once an official release (@file{M.N}) has been made, the version
identifier is updated to contain @file{M.N.0.90} (dot zero, dot ninety)
as the prefix.  Consequently, @file{M.N.0.90-YYYY-MM-DD-cvs} identifies
CVS versions while @file{M.N.0.90_YYYYMMDD} identifies a snapshot.
Succeeding releases increment the minor minor number (@file{.0} or dot
zero).  Succeeding draft release candidates increment the minor minor
minor number (@file{.90}). Since @value{GDBN} no longer makes minor
minor minor releases (e@.g@. @file{5.1.0.1}), there is no potential
version number conflict.

The following a example illustrates this sequence using @file{5.1} as
the previous (@file{m.n}) release series and @file{5.2} @file{M.N} as
the current release series.

@example
5.1.90-YYYY-MM-DD-cvs
5.1.91 (draft release candidate)
5.1.91-YYYY-MM-DD-cvs
5.1.92 (draft release candidate)
5.1.92-YYYY-MM-DD-cvs
5.1.93 (a lie, really 5.2)
5.2 (release)
5.2.0.90-YYYY-MM-DD-cvs
5.2.1 (release)
5.2.1.90-YYYY-MM-DD-cvs
@end example

@itemize @bullet
@item
Minor minor minor draft release candidates such as @file{5.2.0.91) were
intentionally omitted from the example, such release candidates will
most likely never be made.
@item
@file{5.1.93} is described as @emph{a lie} since the bziped tar ball
@file{gdb-5.1.93.tar.bz2} is just the @file{gdb-5.2.tar} file renamed an
compressed.
@end itemize

@subsection Branches

Releases 5.0 and 5.2 used branch 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 5.2 is trying out:

@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.}