This is the mail archive of the
gdb@sourceware.cygnus.com
mailing list for the GDB project.
patch database proposal
- To: gdb at sourceware dot cygnus dot com
- Subject: patch database proposal
- From: Jim Blandy <jimb at cygnus dot com>
- Date: Fri, 25 Feb 2000 13:27:13 -0500 (EST)
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.