[rfa/doc] Versions and Branches

[rfa/doc] Versions and Branches

[Andrew Cagney]

[-- Attachment #1: Type: text/plain, Size: 95 bytes --]

Hello,

This is the revised version/branch section of gdbint.texinfo.  Looking 
beter?

Andrew

[-- Attachment #2: diffs --]
[-- Type: text/plain, Size: 3965 bytes --]

2002-03-15  Andrew Cagney  <ac131313@redhat.com>

	* gdbint.texinfo (Releasing GDB): Add section ``Version
	identifiers'' and Branch Names''

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.67
diff -u -r1.67 gdbint.texinfo
--- gdbint.texinfo	2002/03/04 20:38:10	1.67
+++ gdbint.texinfo	2002/03/15 06:53:05
@@ -4822,6 +4822,106 @@
 @chapter Releasing @value{GDBN}
 @cindex making a new release of gdb
 
+@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-MM-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.minor} from of the previous release series
+but with @var{.90} appended.  As draft releases are drawn from the
+branch, the minor minor number (@var{.90}) is incremented.  Once the
+first release (@var{M.N}) has been made, the version prefix is updated
+to @var{M.N.0.90} (dot zero, dot ninety).  Follow on releases have an
+incremented minor minor version number (@var{.0}).
+
+Using @var{5.1} (previous) and @var{5.2} (current), the example below
+illustrates a typical sequence of version identifiers:
+
+@table @var
+@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
+
+Notes:
+
+@itemize @bullet
+@item
+Minor minor minor draft release candidates such as @var{5.2.0.91} have
+been omitted from the example.  Such release candidates are, typically,
+never made.
+@item
+For @var{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
+
+To avoid version conflicts, vendors are expected to modify the file
+@file{gdb/version.in} to include a vendor unique alphabetic identifier
+(an an official @value{GDBN} release never uses alphabetic characters in
+its version identifer).
+
+Since @value{GDBN} does not make minor minor minor releases
+(e@.g@. @var{5.1.0.1}) the conflict between that and a minor minor draft
+release identifier (e@.g@. @var{5.1.0.90}) is avoided.
+
+
+@subsection Branches
+
+@value{GDBN} draws a release series (@var{5.2}, @var{5.2.1}, @dots{})
+from a single release branch (@var{gdb_5_2-branch}).  Since minor minor
+minor releases (@var{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).
+
+Releases @var{5.0} and @var{5.1} used branch and release 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 @var{5.2} is trialing the branch and release tags:
+
+@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.}
+
+
 @section Obsolete any code
 
 Before anything else, poke the other developers (and around the source

Re: [rfa/doc] Versions and Branches

[Eli Zaretskii]

> Date: Fri, 15 Mar 2002 01:54:52 -0500
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> This is the revised version/branch section of gdbint.texinfo.  Looking 
> beter?

Yes, thanks.  But it looks like I confused you too much with my
previous comments about @var.  Sorry...

> +@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.minor} from of the previous release series
> +but with @var{.90} appended.  As draft releases are drawn from the
> +branch, the minor minor number (@var{.90}) is incremented.  Once the
> +first release (@var{M.N}) has been made, the version prefix is updated
> +to @var{M.N.0.90} (dot zero, dot ninety).  Follow on releases have an
> +incremented minor minor version number (@var{.0}).

Doesn't makeinfo whine about unlikely characters in @var or something?
If it does, use @var{n}.@var{m} instead of @var{n.m} etc.

In any case, a literal numbered version, such as 5.1.90, should _never_
be in @var.  @var is used for symbols that stand for something else.
For example, m and n in "m.n" each stand for some number, thus they
should have the @var markup.  By contrast, 5, 1, and 90 in "5.1.90"
stand for themselves and nothing else, i.e. they are literal numbers,
not variables.  So @var should not be used with them.

> +@table @var
> +@item 5.1.1

Accordingly, this table should not use @var, but @asis.

> +Since @value{GDBN} does not make minor minor minor releases
> +(e@.g@. @var{5.1.0.1}) the conflict between that and a minor minor draft
> +release identifier (e@.g@. @var{5.1.0.90}) is avoided.

"e.g." should be written as is:

  ...the conflict between that and a minor minor draft release
  identifier (e.g., 5.1.0.1) is avoided.

In general, "e.g." is _always_ followed by a comma (which you omitted ;-),
and so TeX will never think its dot ends a sentence.  So there's no need
to do anything about it.  By contrast, "i.e." is _not_ followed by a comma
so you need to write "i.e.@:".  (Note: "@:", not "@.", as you did in the
text above.  "@." is for the opposite case: when a sentence ends with
a single capital letter, which might make TeX think it's not a sentence
end.)

Re: [rfa/doc] Versions and Branches

[Andrew Cagney]

> +@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.minor} from of the previous release series
>> +but with @var{.90} appended.  As draft releases are drawn from the
>> +branch, the minor minor number (@var{.90}) is incremented.  Once the
>> +first release (@var{M.N}) has been made, the version prefix is updated
>> +to @var{M.N.0.90} (dot zero, dot ninety).  Follow on releases have an
>> +incremented minor minor version number (@var{.0}).
> 
> 
> Doesn't makeinfo whine about unlikely characters in @var or something?
> If it does, use @var{n}.@var{m} instead of @var{n.m} etc.

I didn't notice it.

So that I know I've got this straight:

	@var{.0} -> .0
	@var{M.N.0.90} -> @var{M}.@var{N}.0.90

BTW, are there any guidelines available online for this?

thanks!
Andrew

(I got the e.g.@: right on the second attempt)

Re: [rfa/doc] Versions and Branches

[Eli Zaretskii]

> Date: Fri, 15 Mar 2002 11:41:38 -0500
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> So that I know I've got this straight:
> 
> 	@var{.0} -> .0
> 	@var{M.N.0.90} -> @var{M}.@var{N}.0.90

Yes.  Sorry I didn't make this clear earlier.

> BTW, are there any guidelines available online for this?

The Texinfo manual should be it.  In Info, type "i var RET", and you
will be reading the explanations.  If you think there's something
missing there (more examples?, please send a bug report to
bug-texinfo@gnu.org.

Re: [rfa/doc] Versions and Branches

[Andrew Cagney]

[-- Attachment #1: Type: text/plain, Size: 627 bytes --]

> Date: Fri, 15 Mar 2002 11:41:38 -0500
>> From: Andrew Cagney <ac131313@cygnus.com>
>> 
>> So that I know I've got this straight:
>> 
>> @var{.0} -> .0
>> @var{M.N.0.90} -> @var{M}.@var{N}.0.90
> 
> 
> Yes.  Sorry I didn't make this clear earlier.
> 
> 
>> BTW, are there any guidelines available online for this?
> 
> 
> The Texinfo manual should be it.  In Info, type "i var RET", and you
> will be reading the explanations.  If you think there's something
> missing there (more examples?, please send a bug report to
> bug-texinfo@gnu.org.

Time to curl up and read the manual from end to end.

Try the attached.

Andrew



[-- Attachment #2: diffs --]
[-- Type: text/plain, Size: 3900 bytes --]

2002-03-15  Andrew Cagney  <ac131313@redhat.com>

	* gdbint.texinfo (Releasing GDB): Add section ``Version
	identifiers'' and Branch Names''

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.67
diff -u -r1.67 gdbint.texinfo
--- gdbint.texinfo	2002/03/04 20:38:10	1.67
+++ gdbint.texinfo	2002/03/17 15:04:08
@@ -4822,6 +4822,105 @@
 @chapter Releasing @value{GDBN}
 @cindex making a new release of gdb
 
+@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:
+
+@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
+
+Notes:
+
+@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
+
+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).
+
+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 Branches
+
+@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).
+
+Releases 5.0 and 5.1 used branch and release 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 @var{5.2} is trialing the branch and release tags:
+
+@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.}
+
+
 @section Obsolete any code
 
 Before anything else, poke the other developers (and around the source

Re: [rfa/doc] Versions and Branches

[Eli Zaretskii]

On Sun, 17 Mar 2002, Andrew Cagney wrote:

> Try the attached.

A stray "@var{5.2}" crept in.  Other than that, it's perfectly okay.
Thanks.