Re: [patch;rfa:doc] 5.2.50 on mainline

["Eli Zaretskii" <eliz@gnu.org>]

> Date: Tue, 05 Oct 2004 14:35:34 -0400
> From: Andrew Cagney <cagney@gnu.org>
> Cc: gdb-patches@sources.redhat.com
> 
> > Index: doc/ChangeLog
> > 2004-09-21  Andrew Cagney  <cagney@gnu.org>
> > 
> > 	* gdbint.texinfo (Versions and Branches): New chapter.
> > 	(Releasing GDB): Delete "Versions and Branches" section.
> > 	(Top): Add "Versions and Branches".
> 
> Ping (but Joel made some comments).

Sorry, I missed the original message.  My comments to the doco are
below.

I do agree with Joel: his suggestion shows better the development
mainline, and does not contradict your desire to see the lineage as a
straight line, as 5.2 pretests and 5.2.1 are still on the same line.

> ! @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})

Do these longish @item's pass TeX without triggering overfull hbox
warnings?  If such messages do pop up, perhaps make the strings inside
@var shorter, e.g. "pl" instead of "patchlevel".

> ! a vendor specific relese of @value{GDBN}, that while based on
                        ^^^^^^
A typo (please run through a speller before committing).

> ! @var{patchlevel} is changed to .90.  As draft releases are
> ! drawn from the branch, the @var{patchlevel} is incremented is
> ! incremented.

There are 2 "is incremented" in the last sentence.

> ! Once the first release (@var{M}.@var{N}) has been made,
> ! the version prefix is updated to @var{major}.@var{minor}.0.90.

Here you introduce M and N which somehow relate to "major" and
"minor", but you don't explain the relationship.  Can't we continue to
use the same symbols throughout?

> ! Using 5.1 (previous) and 5.2 (current), the example below illustrates
> ! a typical sequence:

Again, to make the relation to symbols in @var, it is better to say
something like

  If the previous @value{GDBN} version is 5.1 and the current version
  is 5.2, then, substituting 5 for @var{major} and 1 or 2 for
  @var{minor}, here's an illustration of a typical sequence:

> ! Since @value{GDBN} does not make minor minor minor releases

I'd suggest "..does not make @var{minor1}.@var{minor2}.@var{minor3}
releases" here (assuming I understood right what you wanted to say).

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

Same here.

> ! @value{GDBN} uses the following release branch tags:
>   
> ! @smallexample
> ! gdb_N_M-YYYY-MM-DD-branchpoint
> ! gdb_N_M-branch
> ! gdb_M_N-YYYY-MM-DD-release
> ! @end smallexample

There should be @var's inside @smallexample as well, again for
consistency and less confusion potential.

> ! @emph{Pragmatics: The branchpoint and release tags need to identify when
> ! a branch and release are made.

I'm guessing that ``when a branch and release are made'' refers to the
YYYY-MM-DD thing.  If so, please add some reference to @var{YYYY}
etc. in this text, so that the reader knows what you mean by "when".

> ! The branch tag, denoting the head of the
> ! branch, does not have this criteria.}

It seems like "does not have this criteria" is not the best way of
putting this.  Would "does not need this" express correctly what you
wanted to say?

> ! @section Vendor Branches

Why no @cindex entry here?

>   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).  E.g., @samp{5.2widgit2}, or @samp{5.2 (Widgit
> ! Inc Patch 2)}.

Given the discussions about finding out MI versions, do we perhaps
want to tell vendors not to embed whitespace in their identifiers?

> ! @section Experimental Branches
> ! @cindex branches

This @cindex entry sounds too general to put here.  How about

  @cindex experimental branches

?

> ! All changes committed to a branch shall also be posted to the
> ! @email{gdb-patches@@sources.redhat.com, the @value{GDBN} patches}
> ! mailing list.

This usage of @email is not a good idea (please look at what makeinfo
and TeX produce from it, and you will see what I mean).  I suggest
something like this instead:

   All changes committed to a branch shall also be posted to
   @email{gdb-patches@@sources.redhat.com, the @value{GDBN} patches
   mailing list}.

> ! @item all commits shall be covered by an assignment

Don't you need "should be covered"?

> ! @item a branch shall to be focused

Same here, and also I think "to" should be deleted.

In addition, I personally don't understand what it means for a branch
to be ``focused''.  Can you explain?

> ! @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).

Would it help to have an example of an actual CVS command here that
creates the branch?  Or at least a reference to the commands you show
later in the section?

> ! The file @file{gdb/version.in} shall be modified so that it identifes
                                                                ^^^^^^^^^
A typo.

> ! To simplify the identification of @value{GDBN} branches, the following
> ! branch taging convention is strongly recommended:
           ^^^^^^
"tagging"

> ! @smallexample
> ! 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

Please make sure this and the other examples don't trigger overfull
hbox messages from TeX.