[patch;rfa:doc] 5.2.50 on mainline

Andrew Cagney cagney@gnu.org
Wed Oct 6 22:20:00 GMT 2004


I think I've covered this, I've made notes where I think it's helpful:
> 
> 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.

Changed, also changed to 6.[12] so that it looks more current, also uses 
gdb_6_2-branch.

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

It's the only chapter that does!  I did add one @* though.

>>> ! a vendor specific relese of @value{GDBN}, that while based on

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

The original original patch used M/N everywere but then I changed to to 
major/minor - missed that in the switch.  Fixed.


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

stolen.

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

I deleted these.  With major.minor.patchlevel, the phrase and intent no 
longer applies -> it's clear that there are no further levels.

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

The M/N were also fixed.

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

Done.

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

Rewoded.

>>> ! @section Vendor Branches
> 
> 
> Why no @cindex entry here?

Added.

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

I don't see it as a problem.

>>> ! @section Experimental Branches
>>> ! @cindex branches
> 
> 
> This @cindex entry sounds too general to put here.  How about
> 
>   @cindex experimental branches
> 
> ?

changed

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

changed

>>> ! @item all commits shall be covered by an assignment
> 
> 
> Don't you need "should be covered"?

Shall.  It's a strict requirement.

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

I reworded it.

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

I added an anchor.

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

clean.

Andrew

-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: diffs
URL: <http://sourceware.org/pipermail/gdb-patches/attachments/20041006/ae63c579/attachment.ksh>


More information about the Gdb-patches mailing list