From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 19354 invoked by alias); 11 Oct 2004 06:30:22 -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 19346 invoked from network); 11 Oct 2004 06:30:22 -0000 Received: from unknown (HELO mx1.redhat.com) (66.187.233.31) by sourceware.org with SMTP; 11 Oct 2004 06:30:22 -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 i9B6UHEF022074 for ; Mon, 11 Oct 2004 02:30:22 -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 i9B6UFr04811; Mon, 11 Oct 2004 02:30:15 -0400 Received: from gnu.org (localhost [127.0.0.1]) by localhost.redhat.com (Postfix) with ESMTP id B3D6828CD; Mon, 11 Oct 2004 02:29:56 -0400 (EDT) Message-ID: <416A2864.8070603@gnu.org> Date: Mon, 11 Oct 2004 06:30:00 -0000 From: Andrew Cagney User-Agent: Mozilla/5.0 (X11; U; NetBSD macppc; en-GB; rv:1.4.1) Gecko/20041009 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> <41646F7D.4070005@gnu.org> <01c4ad1b$Blat.v2.2.2$76b4d020@zahav.net.il> In-Reply-To: <01c4ad1b$Blat.v2.2.2$76b4d020@zahav.net.il> Content-Type: multipart/mixed; boundary="------------000506070807060702030809" X-SW-Source: 2004-10/txt/msg00190.txt.bz2 This is a multi-part message in MIME format. --------------000506070807060702030809 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Content-length: 751 >>>>>> >>> ! @item all commits shall be covered by an assignment >>> >>>> > Don't you need "should be covered"? >> >>> >>> Shall. It's a strict requirement. > > > Well, the text says ``guidelines'', not ``requirements''. Also, do we > really expect the reader of those to be fluent with the conventions of > MIL-STD-489 and its ilk? If not, ``shall'' sounds bad English in this > context, IMHO. As a "guideline" it's pretty strong - it met with clear support when proposed so I don't think anyone would not follow it. And in the case of code, it really does need to be covered by an assignment (except when trivial) - that just explicitly stating the rule that applies to the mainline. Anyway, I've removed the shall. Look ok? Andrew --------------000506070807060702030809 Content-Type: text/plain; name="diffs" Content-Transfer-Encoding: 7bit Content-Disposition: inline; filename="diffs" Content-length: 11320 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: doc/gdbint.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v retrieving revision 1.224 diff -p -u -r1.224 gdbint.texinfo --- doc/gdbint.texinfo 12 Sep 2004 15:20:49 -0000 1.224 +++ doc/gdbint.texinfo 11 Oct 2004 06:14:39 -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 has 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 are 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 are 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 is 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 tracks 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 --------------000506070807060702030809--