[maint] Guidelines for experimental branches

[maint] Guidelines for experimental branches

[Andrew Cagney]

[-- Attachment #1: Type: text/plain, Size: 423 bytes --]

Hello,

The attached is one bit of fallout from a recent discussion.  It's a 
proposed policy for branches.

The intent is to provide [strong] guidelines for how an experimental 
branch should be run.  It also provides somewhere to document any 
branches that people create.

Comments, throughts, overspecified?

To make my life easier I wrote it directly in texinfo (richard it 
contains several points you made).

Andrew

[-- Attachment #2: diffs --]
[-- Type: text/plain, Size: 3775 bytes --]

2003-03-03  Andrew Cagney  <cagney@redhat.com>

	* gdbint.texinfo (Branches): New chapter.  With suggestions from
	Richard Earnshaw.

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.125
diff -u -r1.125 gdbint.texinfo
--- gdbint.texinfo	2 Mar 2003 04:02:25 -0000	1.125
+++ gdbint.texinfo	3 Mar 2003 23:17:36 -0000
@@ -91,6 +91,7 @@
 * Coding::
 * Porting GDB::
 * Releasing GDB::
+* Experimental Branches::
 * Testsuite::
 * Hints::
 
@@ -6208,6 +6209,93 @@
 @section Post release
 
 Remove any @code{OBSOLETE} code.
+
+@node Experimental Branches
+@chapter Experimental Branches
+@cindex branches
+
+@section Guidelines
+
+@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.
+
+The following are a set of guidelines for creating such branches:
+
+@table @emph
+
+@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 the
+@email{gdb-patches@@sources.redhat.com, the @value{GDBN} patches}
+mailing list.  While commentary on such chages are encouraged, people
+should remember that the changes only apply to a branch.
+
+@item all commits shall be covered by an assignment
+This saves @value{GDBN} from the situation where a branch might become
+contaminated.
+
+@item a branch shall to be focused
+A de-focused branch invariably generates lint (unnecessary and irelevant
+change).  Cleanups, where identified, should 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} or @code{gdb+dejagnu} should be
+specified when creating a branch (branches of individual files should be
+avoided).
+
+@end table
+
+@section Tags
+
+To simplify the identification of @value{GDBN} branches, the following
+branch taging convention is 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:
+@smallexample
+cvs rtag @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint gdb+dejagnu
+cvs rtag -b -r @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint \
+   @var{owner}_@var{name}-@var{YYYYMMDD}-branch gdb+dejagnu
+@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+dejagnu
+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.
+
+@end table
+
+@section Active branches
+
+@subheading cagney_@var{offbyone}-20030303-branch
+Test fixes to a problem with the wrong frame ID unwind method being
+called (with the wrong frame cache).
 
 @node Testsuite
 

Re: [maint] Guidelines for experimental branches

[David Carlton]

On Mon, 03 Mar 2003 18:22:59 -0500, Andrew Cagney <ac131313@redhat.com> said:

> Comments, throughts, overspecified?

Great!  I was planning to write something up containing the mechanics
of branch creation, but you've beaten me to it.

> +@item a branch shall contain the entire @value{GDBN} module
> +The @value{GDBN} module @code{gdb} or @code{gdb+dejagnu} should be
> +specified when creating a branch (branches of individual files should be
> +avoided).

Maybe also mention insight, insight+dejagnu?  (And, for that matter,
to give some guidance as to when "+dejagnu" is appropriate?)

> +@smallexample
> +cvs rtag @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint gdb+dejagnu
> +cvs rtag -b -r @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint \
> +   @var{owner}_@var{name}-@var{YYYYMMDD}-branch gdb+dejagnu
> +@end smallexample

It might also be nice to give an example of how to actually check out
the branch here.

> +
> +@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+dejagnu
> +cvs update \
> +   -j@var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint
> +   -j@var{owner}_@var{name}-@var{yyyymmdd}-mergepoint
> +@end smallexample

I would consider adding "-kk" to the cvs update flags: it doesn't
matter for core GDB, but I _think_ it will help for, say, TCL.  Also,
might it be useful to give some guidance about how to detect
collisions (redirecting stdout+stderr to a file, etc.), or is that not
necessary?

> +@section Active branches
> +
> +@subheading cagney_@var{offbyone}-20030303-branch
> +Test fixes to a problem with the wrong frame ID unwind method being
> +called (with the wrong frame cache).

My first reaction is "shouldn't this be on a web page somewhere?".  On
the other hand, it's not like I've ever edited the GDB web pages; it's
easier for branch creaters to edit gdbint.texinfo.  But I still think
this sort of info should be accessible via a web page; maybe put a
link on a GDB web page (current cvs?) to a web copy of this section of
gdbint.texinfo?

David Carlton
carlton@math.stanford.edu

Re: [maint] Guidelines for experimental branches

[Andrew Cagney]

>> +@item a branch shall contain the entire @value{GDBN} module
>> +The @value{GDBN} module @code{gdb} or @code{gdb+dejagnu} should be
>> +specified when creating a branch (branches of individual files should be
>> +avoided).
> 
> 
> Maybe also mention insight, insight+dejagnu?  (And, for that matter,
> to give some guidance as to when "+dejagnu" is appropriate?)

You assume I know the answer :-)

>> +@smallexample
>> +cvs rtag @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint gdb+dejagnu
>> +cvs rtag -b -r @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint \
>> +   @var{owner}_@var{name}-@var{YYYYMMDD}-branch gdb+dejagnu
>> +@end smallexample
> 
> 
> It might also be nice to give an example of how to actually check out
> the branch here.

True, however ...

>> +
>> +@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+dejagnu
>> +cvs update \
>> +   -j@var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint
>> +   -j@var{owner}_@var{name}-@var{yyyymmdd}-mergepoint
>> +@end smallexample
> 
> 
> I would consider adding "-kk" to the cvs update flags: it doesn't
> matter for core GDB, but I _think_ it will help for, say, TCL.  Also,
> might it be useful to give some guidance about how to detect
> collisions (redirecting stdout+stderr to a file, etc.), or is that not
> necessary?

... this shouldn't be a substitute for the CVS manual (What's missing is 
a reference to the CVS documentation).  My motivation for mentioning the 
above commands was to draw peoples attention to the very efficient rtag :-)

>> +@section Active branches
>> +
>> +@subheading cagney_@var{offbyone}-20030303-branch
>> +Test fixes to a problem with the wrong frame ID unwind method being
>> +called (with the wrong frame cache).
> 
> 
> My first reaction is "shouldn't this be on a web page somewhere?".  On
> the other hand, it's not like I've ever edited the GDB web pages; it's
> easier for branch creaters to edit gdbint.texinfo.

It's on the web :-) All doco is generated daily.

> But I still think
> this sort of info should be accessible via a web page; maybe put a
> link on a GDB web page (current cvs?) to a web copy of this section of
> gdbint.texinfo?

Yes.  A things-to-do-today item is get as many the web pages into 
texinfo.  I figured that I'd put this stuff in texinfo from the start.

To have the link working correctly though, someone (...) will need to 
look at makeinfo since that, unlike texi2html, gives each page a name ...

thanks,
Andrew

Re: [maint] Guidelines for experimental branches

[Eli Zaretskii]

> Date: Mon, 03 Mar 2003 18:22:59 -0500
> From: Andrew Cagney <ac131313@redhat.com>
> 
> The attached is one bit of fallout from a recent discussion.  It's a
> proposed policy for branches.

Fine with me.

> +@item all commits shall be posted
> +All changes committed to a branch shall also be posted to the
> +@email{gdb-patches@@sources.redhat.com, the @value{GDBN} patches}
> +mailing list.

I think "mailing list" should also be inside @email.

Re: [maint] Guidelines for experimental branches

[Michal Ludvig]

Andrew Cagney wrote:
> +@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

Is it necessary to have the date in the name of the branch? IMHO it's 
fine for the branchpoint, as well as for mergepoints, but for the branch 
itself it's useless. People could much better remember words than 
8-digits chunks and having to look on the webpage everytime, when I want 
to check out a branch is boring.
I believe that calling your branch cagney_offbyone-branch would be 
descriptive enough and wouldn't collide with anything.

Well, just my 2 cents.

Michal Ludvig
-- 
* SuSE CR, s.r.o     * mludvig@suse.cz
* (+420) 296.545.373 * http://www.suse.cz

Re: [maint] Guidelines for experimental branches

[Diego Novillo]

In article <3E648828.3080502@suse.cz>, Michal Ludvig wrote:
> Andrew Cagney wrote:
>> +@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
> 
> Is it necessary to have the date in the name of the branch? IMHO it's 
> fine for the branchpoint, as well as for mergepoints, but for the branch 
> itself it's useless. People could much better remember words than 
> 8-digits chunks and having to look on the webpage everytime, when I want 
> to check out a branch is boring.
>
If the branch is long lived, you may want to re-create it more than once
for performance reasons.  As you get farther and farther from the
branchpoint, CVS operations get increasingly slower.  If dates are too
long, you could also use 2-3 digit numbers.


Diego.

Re: [maint] Guidelines for experimental branches

[Michal Ludvig]

Diego Novillo wrote:
> In article <3E648828.3080502@suse.cz>, Michal Ludvig wrote:
> 
>>Is it necessary to have the date in the name of the branch? IMHO it's 
>>fine for the branchpoint, as well as for mergepoints, but for the branch 
>>itself it's useless. People could much better remember words than 
>>8-digits chunks and having to look on the webpage everytime, when I want 
>>to check out a branch is boring.
> 
> If the branch is long lived, you may want to re-create it more than once
> for performance reasons.  As you get farther and farther from the
> branchpoint, CVS operations get increasingly slower.  If dates are too
> long, you could also use 2-3 digit numbers.

So, could we say, that the date in there it optional?

Michal Ludvig
-- 
* SuSE CR, s.r.o     * mludvig@suse.cz
* (+420) 296.545.373 * http://www.suse.cz

Re: [maint] Guidelines for experimental branches

[Diego Novillo]

On Wed, 2003-03-05 at 05:32, Michal Ludvig wrote:

> So, could we say, that the date in there it optional?
> 
Yes, of course.  I was only rationalizing why would you want to have it
in the branch name.


Diego.

Re: [maint] Guidelines for experimental branches

[Andrew Cagney]

> On Wed, 2003-03-05 at 05:32, Michal Ludvig wrote:
> 
> 
>> So, could we say, that the date in there it optional?
>> 
> 
> Yes, of course.  I was only rationalizing why would you want to have it
> in the branch name.

It's a recommendation.  The experience I've had matches diego - having 
to abandon old branches and cut new ones (just a shame that CVS doesn't 
have branch aliases).

Andrew

PS: If nothing else, the date is a daily reminder of how old the branch 
is :-)

Re: [maint] Guidelines for experimental branches

[Michael Elizabeth Chastain]

I dunno if there's anywhere to document this, but I offer my testbed
services to any branch that wants to get testbedded.  Just let me
know the branch name and I'll do diff reports versus gdb 5.3 or
your branchpoint or gdb HEAD or whatever works for you.

Michael C