[patch;rfa:doc] 5.2.50 on mainline
Eli Zaretskii
eliz@gnu.org
Wed Oct 6 11:08:00 GMT 2004
> 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.
More information about the Gdb-patches
mailing list