From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 14637 invoked by alias); 6 Oct 2004 11:08:25 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 14627 invoked from network); 6 Oct 2004 11:08:22 -0000 Received: from unknown (HELO legolas.inter.net.il) (192.114.186.24) by sourceware.org with SMTP; 6 Oct 2004 11:08:22 -0000 Received: from zaretski ([80.230.143.237]) by legolas.inter.net.il (MOS 3.5.3-GR) with ESMTP id CTL55419 (AUTH halo1); Wed, 6 Oct 2004 13:08:06 +0200 (IST) Date: Wed, 06 Oct 2004 11:08:00 -0000 From: "Eli Zaretskii" To: Andrew Cagney Message-ID: <01c4ab94$Blat.v2.2.2$7296a000@zahav.net.il> Content-Transfer-Encoding: 7BIT Content-Type: text/plain; charset=ISO-8859-1 CC: gdb-patches@sources.redhat.com In-reply-to: <4162E976.50803@gnu.org> (message from Andrew Cagney on Tue, 05 Oct 2004 14:35:34 -0400) Subject: Re: [patch;rfa:doc] 5.2.50 on mainline Reply-to: Eli Zaretskii References: <41508EC1.9040506@gnu.org> <4162E976.50803@gnu.org> X-SW-Source: 2004-10/txt/msg00112.txt.bz2 > Date: Tue, 05 Oct 2004 14:35:34 -0400 > From: Andrew Cagney > Cc: gdb-patches@sources.redhat.com > > > Index: doc/ChangeLog > > 2004-09-21 Andrew Cagney > > > > * 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.