patch database proposal

[Jim Blandy <jimb at cygnus dot com>]

Here's a tentative proposal for how the patch database should work.
In reality, a good part of this is set up and ready to go, but there's
nothing we can't revise, in the presence of good ideas or persuasive
criticism.

Please let me know what you think; post your comments to the list.

----

If you've written a patch for GDB, either to fix a bug or to improve
the program, you should make sure it gets into the GDB patch database.
The GDB patch database is a GNATS database created to help GDB's
maintainers keep track of patches that need reviewing, and helps you
stay on top of what's happening to your patch.

Anyone can submit a patch.  There are two ways to do so:

- Visit the GDB Patch Submission page [Jason will supply URL], and
  submit your patch there.

- Submit your patches via E-mail, by sending a message to
  `gdb-patches-gnats@sourceware.cygnus.com'.  We have a template for
  mail messages [link here].  Following this template helps make sure
  we have the information we need to choose a reviewer for your patch,
  and to do the review itself.

We'd prefer that you use the web form, if possible, because that
provides more helpful prompts, and checks your input more thoroughly.

The database assigns each new patch a number, like `gdb-patch/209'.
Whenever you send mail regarding your patch, be sure to include the
address `gdb-patches-gnats@sourceware.cygnus.com' in the CC list, and
make sure the message subject starts with `gdb-patch/209: ', or
whatever your patch number is.  This way, GNATS will automatically log
the discussion along with the patch in the database.

Once you've submitted your patch, you can visit [another URL] to check
on its status, or to search the patch database in various ways.  Each
patch in the database has a set of headers, much like a mail message;
the two most interesting headers to look at are:

- `Responsible' --- this is the name of the person currently
  responsible for moving the patch forward.

- `State' --- the current status of the patch.

Here are the different states a patch might be in:

- `unclaimed'

  If the database software can't figure out automatically which
  maintainer should evaluate your patch, then it declares the patch
  `unclaimed', and sets the `Responsible' person to the GDB patch
  secretary.  It is then the secretary's job to find someone who can 
  review the patch, and change the patch's `State' and `Responsible'
  headers appropriately.

  Also, if the maintainer responsible for a patch decides that they
  can't process it --- for example, they might know they won't be able
  to evaluate it promptly --- then they can put it back in the
  `unclaimed' state.  As before, the patch secretary should find
  someone else to tend to it.  The patch database logs all changes
  to a patch's state or responsible party, along with all mail
  communication about the patch, which can help the new person pick
  the patch where it left off.

- `claimed'

  The person named in the patch's `Responsible' header has volunteered
  or been designated to review the patch, but they haven't made any
  decision about it yet, or they haven't gotten around to looking at
  it yet.

  The maintainer indicates his or her decision by putting the patch in
  one of the states below.

  If the patch requires additional maintainers' approval, then the
  maintainer should leave the patch in the `claimed' state, and simply
  change the `Responsible' field to the next maintainer in line.
  Since all changes in responsibility are logged with the patch, each
  maintainer can tell when the review process is complete.  The last
  maintainer to evaluate the patch should actually change the state to
  something more conclusive.

  As the name suggests, patch claims are voluntary.  Maintainers
  should feel free to claim interesting unclaimed patches for
  themselves, and to trade or reallocate patches amongst themselves as
  appropriate, simply by changing patches' `State' and `Responsible'
  headers.  Assignments made automatically by the database software,
  or manually by the patch secretary, are simply an optimization,
  meant to help the process run more smoothly.

  Of course, if a maintainer consistently fails to review patches in a
  timely fashion, the team will eventually suggest that they step
  down, or share the responsibility with someone more responsive.

- `feedback'

  This state indicates that the maintainer feels the patch needs
  revision, or that the author's intent is unclear and the patch
  should be further explained.  It is now the responsibility of the
  original author of the patch to satisfy the maintainer's concerns,
  to allow the patch to move forward.

  The maintainer's concerns should always be recorded with the patch
  somehow, either in a mail message logged with the patch, or in the
  state change message.

  Note that the maintainer is still responsible for patches in this
  state.  If the author is slow to respond, the maintainer must pursue
  the matter, or put the patch in the `rejected' state (described
  below) if the author doesn't reply.

- `prereqs'

  The maintainer approves of the patch, but can't apply it until some
  other change is made --- some other patch must be applied first, for
  example.  The maintainer should explain what they are waiting for in
  the patch record.  It is the maintainer's responsibility to notice
  when the prerequisites have been met, and move the patch along.

- `accepted'

  The maintainer has decided to apply the patch, and has accepted
  responsibility for whatever further work is necessary to get it into
  the sources.

- `applied'

  The maintainer has applied the patch, and expects no further work on
  that patch to be necessary.

- `rejected'

  This state represents several possible outcomes:

  - The maintainer has decided that the patch should not be applied, and
    is not expecting to do revisions or further work on that patch.

  - The patch's author has withdrawn it, and the maintainer agrees.

  - The patch is actually several smaller changes lumped together;
    the author must resubmit it as several separate patches.

  - The patch is so old that it is no longer useful in revising the
    current sources, and neither the author nor the maintainer has any
    intention of bringing it up to date.

  In any case, the maintainer should explain why the patch was
  rejected, in the patch notes.
  
  Of course, it is always possible for a maintainer to resurrect a
  rejected patch, simply by putting it back in one of the other
  states.

- `papers'

  The maintainer would like to apply the patch, but the patch is large
  enough that it is automatically copyrighted by the author, and
  cannot be applied to the GDB sources.  In this case, the author
  needs to assign his or her copyright interest in the patch to the
  Free Software Foundation; see [link], or the file `gdb/CONTRIBUTE'
  in the GDB source tree, for details about this.

[We'll work in full documentation for the other headers somewhere, but
this page is mostly about the process, which is the least obvious
part.]


If you're interested in monitoring patch activity, you may wish to
subscribe to `gdb-patches-prs@sourceware.cygnus.com'.  This mailing
list receives:

  - messages announcing newly submitted patches

  - all discussion about existing patches

  - messages indicating that a patch has changed state, and why

To subscribe, [appropriate instructions or link]


If you are having problems using the patch database, send mail to
`gdb-patches-secretary@sourceware.cygnus.com'.  The patch secretary
is responsible for:

  - the quality of the database (removing spam, getting people to use
    the headers in a helpful way, making sure all patches are placed
    in the database [in my experience, every database gets dirty, and
    there needs to be someone working to counteract entropy]);

  - passing `unclaimed' patches to willing and appropriate maintainers;

  - all GDB-specific documentation and web pages supporting the patch
    database; and

  - any other administration specific to the GDB patch database

The patch secretary is not responsible for:

  - technical issues (like evaluating patches);

  - administration of shared sourceware infrastructure, not specific to the
    GDB database (fixing wedged servers, upgrading software, etc.); or

  - prodding unresponsive maintainers.  (General community pressure is
    best for this; beyond that, the prodding needs to be done by
    someone with real authority over their time, like their manager,
    or authority over their maintainership, like the committee that
    made them a maintainer in the first place.)

In the GDB source tree, the file gdb/MAINTAINERS lists the current
patch secretary, along with all the maintainers and the areas they're
responsible for.