[maint] Guidelines for experimental branches

Andrew Cagney
2003-03-03T23:23:02Z

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