[maint] Guidelines for experimental branches

[Andrew Cagney <ac131313 at redhat dot com>]

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
2003-03-03  Andrew Cagney  <cagney at redhat dot 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.
+
+ at node Experimental Branches
+ at chapter Experimental Branches
+ at cindex branches
+
+ at section Guidelines
+
+ at 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:
+
+ at table @emph
+
+ at 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).
+
+ at item all commits shall be posted
+All changes committed to a branch shall also be posted to the
+ at 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.
+
+ at item all commits shall be covered by an assignment
+This saves @value{GDBN} from the situation where a branch might become
+contaminated.
+
+ at 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
+
+ at 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.
+
+ at 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).
+
+ at end table
+
+ at section Tags
+
+To simplify the identification of @value{GDBN} branches, the following
+branch taging convention is recommended:
+
+ at table @code
+
+ at item @var{owner}_ at var{name}-@var{YYYYMMDD}-branchpoint
+ at itemx @var{owner}_ at 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:
+ at smallexample
+cvs rtag @var{owner}_ at var{name}-@var{YYYYMMDD}-branchpoint gdb+dejagnu
+cvs rtag -b -r @var{owner}_ at var{name}-@var{YYYYMMDD}-branchpoint \
+   @var{owner}_ at var{name}-@var{YYYYMMDD}-branch gdb+dejagnu
+ at end smallexample
+
+ at item @var{owner}_ at 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:
+ at smallexample
+cvs rtag @var{owner}_ at var{name}-@var{yyyymmdd}-mergepoint gdb+dejagnu
+cvs update \
+   -j at var{owner}_@var{name}- at var{YYYYMMDD}-branchpoint
+   -j at var{owner}_@var{name}- at var{yyyymmdd}-mergepoint
+ at end smallexample
+ at noindent
+Similar sequences can be used to just merge in changes since the last
+merge.
+
+ at end table
+
+ at section Active branches
+
+ at subheading cagney_ at 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