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

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

[Andrew Cagney]

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

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

[Eli Zaretskii]

> Date: Wed, 06 Mar 2002 21:11:26 -0500
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> @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}.

I suggest to use @var{yyyy}, @var{mm}, etc., since these strings
really stand for something else.

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

Same here with `minor' and `major'.

> major.minor (@file{m.n}) identification with a @file{.90} suffix

and with `m.n'.

> The following a example illustrates this sequence using @file{5.1} as

That "a" should be removed.

> @file{gdb-5.1.93.tar.bz2} is just the @file{gdb-5.2.tar} file renamed an
> compressed.

Should be "and", not "an", I think.

Finally, I wonder if we really need to explain all that in so many
words.  (But I won't object if you think it's useful.)

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

[Andrew Cagney]

> 
> 
> Should be "and", not "an", I think.
> 
> Finally, I wonder if we really need to explain all that in so many
> words.  (But I won't object if you think it's useful.)

If you can think of ways of trimming it down, please do.  I'm just 
trying to get the process down so that the next person doesn't have to 
wonder how/why things are done a certain way :-)

enjoy,
Andrew

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

[Eli Zaretskii]

> Date: Thu, 07 Mar 2002 15:11:43 -0500
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> > Finally, I wonder if we really need to explain all that in so many
> > words.  (But I won't object if you think it's useful.)
> 
> If you can think of ways of trimming it down, please do.

It seemed to me that part about the version-naming scheme is too long.
I thought it could just describe the principles, without so many
examples.

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

[Andrew Cagney]

> Date: Thu, 07 Mar 2002 15:11:43 -0500
>> From: Andrew Cagney <ac131313@cygnus.com>
>> 
> 
>> > Finally, I wonder if we really need to explain all that in so many
>> > words.  (But I won't object if you think it's useful.)
> 
>> 
>> If you can think of ways of trimming it down, please do.
> 
> 
> It seemed to me that part about the version-naming scheme is too long.
> I thought it could just describe the principles, without so many
> examples.

Hmm, true - zap zap zap.
thanks.
Andrew