[maint] Guidelines for experimental branches

[Andrew Cagney <ac131313@redhat.com>]

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