From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 23973 invoked by alias); 6 Oct 2004 22:20:16 -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 23939 invoked from network); 6 Oct 2004 22:20:14 -0000 Received: from unknown (HELO mx1.redhat.com) (66.187.233.31) by sourceware.org with SMTP; 6 Oct 2004 22:20:14 -0000 Received: from int-mx1.corp.redhat.com (int-mx1.corp.redhat.com [172.16.52.254]) by mx1.redhat.com (8.12.11/8.12.10) with ESMTP id i96MK9eS014345 for ; Wed, 6 Oct 2004 18:20:14 -0400 Received: from localhost.redhat.com (porkchop.devel.redhat.com [172.16.58.2]) by int-mx1.corp.redhat.com (8.11.6/8.11.6) with ESMTP id i96MJwr21856; Wed, 6 Oct 2004 18:19:58 -0400 Received: from gnu.org (localhost [127.0.0.1]) by localhost.redhat.com (Postfix) with ESMTP id 039AC28D2; Wed, 6 Oct 2004 18:19:41 -0400 (EDT) Message-ID: <41646F7D.4070005@gnu.org> Date: Wed, 06 Oct 2004 22:20:00 -0000 From: Andrew Cagney User-Agent: Mozilla/5.0 (X11; U; NetBSD macppc; en-GB; rv:1.4.1) Gecko/20040831 MIME-Version: 1.0 To: Eli Zaretskii Cc: gdb-patches@sources.redhat.com Subject: Re: [patch;rfa:doc] 5.2.50 on mainline References: <41508EC1.9040506@gnu.org> <4162E976.50803@gnu.org> <01c4ab94$Blat.v2.2.2$7296a000@zahav.net.il> In-Reply-To: <01c4ab94$Blat.v2.2.2$7296a000@zahav.net.il> Content-Type: multipart/mixed; boundary="------------000906050405060100010403" X-SW-Source: 2004-10/txt/msg00123.txt.bz2 This is a multi-part message in MIME format. --------------000906050405060100010403 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Content-length: 5668 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 --------------000906050405060100010403 Content-Type: text/plain; name="diffs" Content-Transfer-Encoding: 7bit Content-Disposition: inline; filename="diffs" Content-length: 11336 2004-10-06 Andrew Cagney * gdbint.texinfo (Versions and Branches): New chapter. (Releasing GDB): Delete "Versions and Branches" section. (Top): Add "Versions and Branches". Index: gdbint.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v retrieving revision 1.224 diff -p -u -r1.224 gdbint.texinfo --- gdbint.texinfo 12 Sep 2004 15:20:49 -0000 1.224 +++ gdbint.texinfo 6 Oct 2004 22:19:28 -0000 @@ -84,6 +84,7 @@ as the mechanisms that adapt @value{GDBN * Support Libraries:: * Coding:: * Porting GDB:: +* Versions and Branches:: * Releasing GDB:: * Testsuite:: * Hints:: @@ -5368,109 +5369,198 @@ target-dependent @file{.h} and @file{.c} configuration. @end itemize -@node Releasing GDB - -@chapter Releasing @value{GDBN} -@cindex making a new release of gdb +@node Versions and Branches +@chapter Versions and Branches -@section Versions and Branches +@section Versions -@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: +@value{GDBN}'s version is determined by the file +@file{gdb/version.in} and takes one of the following forms: @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 +@item @var{major}.@var{minor} +@itemx @var{major}.@var{minor}.@var{patchlevel} +an official release (e.g., 6.0 or 6.0.1) +@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}) +a vendor specific release of @value{GDBN}, that while based on@* +@var{major}.@var{minor}.@var{patchlevel}_@var{YYYY}@var{MM}@var{DD}, +may contain additional changes @end table -Notes: +@value{GDBN}'s mainline uses the @var{major} and @var{minor} version +numbers from the most recent release branch, with a @var{patchlevel} +of 50. As each new release branch is created, the mainline +@var{major} and @var{minor} version numbers are accordingly updated. + +@value{GDBN}'s release branch uses a similar, but slightly more +complicated scheme. When the branch is first cut, the mainline's +@var{patchlevel} is changed to .90. As draft releases are drawn from +the branch, the @var{patchlevel} is incremented. Once the first +release (@var{major}.@var{minor}) has been made, the version prefix is +updated to @var{major}.@var{minor}.0.90. Follow on releases have an +incremented @var{patchlevel}. + +If the previous @value{GDBN} version is 6.1 and the current version is +6.2, then, substituting 6 for @var{major} and 1 or 2 for @var{minor}, +here's an illustration of a typical sequence: + +@smallexample + + | +6.1.50_2002-03-02-cvs + | + +---------------------------. + | + | | +6.2.50_2002-03-03-cvs 6.1.90 (draft #1) + | | +6.2.50_2002-03-04-cvs 6.1.90_2002-03-04-cvs + | | +6.2.50_2002-03-05-cvs 6.1.91 (draft #2) + | | +6.2.50_2002-03-06-cvs 6.1.91_2002-03-06-cvs + | | +6.2.50_2002-03-07-cvs 6.2 (release) + | | +6.2.50_2002-03-08-cvs 6.2.0.90_2002-03-08-cvs + | | +6.2.50_2002-03-09-cvs 6.2.1 (update) + | | +6.2.50_2002-03-10-cvs + | +6.2.50_2002-03-11-cvs + | + +---------------------------. + | + | | +6.3.50_2002-03-12-cvs 6.2.90 (draft #1) + | | +@end smallexample + +@section Release Branches +@cindex Release Branches + +@value{GDBN} draws a release series (6.2, 6.2.1, @dots{}) from a +single release branch, and identifies that branch using the @sc{cvs} +branch tags: + +@smallexample +gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-branchpoint +gdb_@var{major}_@var{minor}-branch +gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-release +@end smallexample + +@emph{Pragmatics: To help identify the date at which a branch or +release is made, both the branchpoint and release tags include the +date that they are cut (@var{YYYY}@var{MM}@var{DD}) in the tag. The +branch tag, denoting the head of the branch, does not need this.} -@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 +@section Vendor Branches +@cindex vendor branches 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). +its version identifer). E.g., @samp{6.2widgit2}, or @samp{6.2 (Widgit +Inc Patch 2)}. -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. +@section Experimental Branches +@cindex experimental branches +@subsection Guidelines -@subsection Branches +@value{GDBN} permits the creation of branches, cut from the @sc{cvs} +repository, for experimental development. Branches make it possible +for developers to share preliminary work, and maintainers to examine +significant new developments. -@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). +The following are a set of guidelines for creating such branches: -Releases 5.0 and 5.1 used branch and release tags of the form: +@table @emph -@smallexample -gdb_N_M-YYYY-MM-DD-branchpoint -gdb_N_M-YYYY-MM-DD-branch -gdb_M_N-YYYY-MM-DD-release -@end smallexample +@item a branch shall have an owner +The owner can set further policy for a branch, but may not change the +ground rules. In particular, they can set a policy for commits (be it +adding more reviewers or deciding who can commit). + +@item all commits shall be posted +All changes committed to a branch shall also be posted to +@email{gdb-patches@@sources.redhat.com, the @value{GDBN} patches +mailing list}. While commentary on such changes are encouraged, people +should remember that the changes only apply to a branch. + +@item all commits shall be covered by an assignment +This ensures that all changes belong to the Free Software Foundation, +and avoids the possibility that the branch may become contaminated. + +@item a branch shall be focused +A focused branch has a single objective or goal, and does not contain +unnecessary or irrelevant changes. Cleanups, where identified, being +be pushed into the mainline as soon as possible. + +@item a branch shall track mainline. +This keeps the level of divergence under control. It also keeps the +pressure on developers to push cleanups and other stuff into the +mainline. + +@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). @xref{Tags}. + +@item a branch shall be branded using @file{version.in} +The file @file{gdb/version.in} shall be modified so that it identifies +the branch @var{owner} and branch @var{name}, e.g., +@samp{6.2.50_20030303_owner_name} or @samp{6.2 (Owner Name)}. -Release 5.2 is trialing the branch and release tags: +@end table -@smallexample -gdb_N_M-YYYY-MM-DD-branchpoint -gdb_N_M-branch -gdb_M_N-YYYY-MM-DD-release +@subsection Tags +@anchor{Tags} + +To simplify the identification of @value{GDBN} branches, the following +branch tagging convention is strongly recommended: + +@table @code + +@item @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint +@itemx @var{owner}_@var{name}-@var{YYYYMMDD}-branch +The branch point and corresponding branch tag. @var{YYYYMMDD} is the +date that the branch was created. A branch is created using the +sequence: @anchor{experimental branch tags} +@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 + +@item @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint +The tagged point, on the mainline, that was used when merging the branch +on @var{yyyymmdd}. To merge in all changes since the branch was cut, +use a command sequence like: +@smallexample +cvs rtag @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint gdb +cvs update \ + -j@var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint + -j@var{owner}_@var{name}-@var{yyyymmdd}-mergepoint @end smallexample +@noindent +Similar sequences can be used to just merge in changes since the last +merge. -@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.} +@end table +@noindent +For further information on @sc{cvs}, see +@uref{http://www.gnu.org/software/cvs/, Concurrent Versions System}. + +@node Releasing GDB + +@chapter Releasing @value{GDBN} +@cindex making a new release of gdb @section Branch Commit Policy --------------000906050405060100010403--