Re: [Gnu-arch-users] how about a game?

[Andrew Suffield]

This is formatted as a reply, but it's really just a description of
the current state of
address@hidden/bugs-test--test--0

Not everything here has been implemented yet. The current
implementation is a working prototype.

On Fri, Jan 16, 2004 at 12:20:18PM -0800, Tom Lord wrote:
> * Bugs and The Bug List
> 
>   The bug list will be represented as an arch project tree.
>   Each individual bug will correspond to a single file within
>   that tree -- though a bug may have "attachments" (other files)
>   associated with it.

Each bug will correspond to a directory with a name matching
/^\d+\.\S+$/. Only bugs may use directories with names beginning with
a digit. The directory will contain at least the following files:

summary

 rfc822-style description of the bug. The 'header' part
 contains any metadata that is commonly wanted, and the 'body' part
 contains a summary of everything that is currently known about the
 bug (shorter is preferred, and it just needs to describe the current
 state, not any history).

 Required headers are:
  Subject: a one-line description
  Bug-Tree: the full archive/category--branch--version that this bug
            belongs to
  Creation-Date: the date at which this bug was reported

 Optional headers are:
  -

log

 changelog-style history of the bug, in reverse chronological order
 (I'll make up a proper file format later). Every change made by one
 of the command-line or mail processing tools will be noted in
 here. Every change made manually should be noted in here. Every mail
 received will have the subject and msgid noted here, and will be
 copied into the mbox file (see below).

 This file can be used to generate reports that look like this:
 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=21000
 Everything between a pair of horizontal rules on that page is one log
 entry. The same format is generated by expanding the references to
 the mbox file.

It may also contain the following files:

mbox

 An mbox of mails regarding this bug. Msgid must be present in every
 mail and unique within the mbox; it will be added or replaced to
 enforce this if necessary.

>   Every bug will have a symbolic name, suitable for use as a
>   filename.

Every bug will have a serial number, unique within the bug tree
(serial numbers must be assigned centrally).

Every bug will also have a symbolic name, composed of non-space
printable characters.

The direcory will be named "${number}.${name}". The name component may
be freely changed; the number is permanent.

Bugs are globally identified by the tuple (bug tree, number).

>   The structure of the bug tree is ultimately up to the bug masters
>   but I suggest something like this:
> 
>         ./
>          # the queue of scheduled but unassigned bugs
>          # 
>          ./queue/
>            ./queue/000234.some-bug-a
>            ./queue/000235.some-bug-b
>            ./queue/000236.some-bug-c
>            ./queue/000237.some-bug-d
> 
>          # the record of bugs currently being worked on
>          # 
>          ./owned/
>            ./owned/lord/
>              ./owned/lord/000053.some-bug-e
>              ./owned/lord/000142.some-bug-f
>              ./owned/lord/000143.some-bug-g
>              ./owned/lord/000200.some-bug-h
>            ./owned/joe/
>              ./owned/joe/000101.some-bug-i
>              ./owned/joe/000122.some-bug-j
>            ...
> 
> 
>          # this list of bugs received but not yet scheduled
>          # 
>          ./incoming/
>            ./high-priority/
>              ./high-priority/some-bug-k
>              ./high-priority/some-bug-l
>              ./high-priority/some-bug-m
>            ./avg-priority/
>              ./avg-priority/some-bug-n
>              ./avg-priority/some-bug-o
>              ./avg-priority/some-bug-p
>            ...
> 
>          # the record of bugs fixed
>          # 
>          ./done/
>            ./done/000001.some-bug-q
>            ./done/000002.some-bug-r
>            ./done/000004.some-bug-s
> 
>          # the record of bugs rejected
>          # 
>          ./rejected
>            ./rejected/000003.some-bug-t
> 
> 
>   I'll add more to the structure of the bug tree later on in the rules
>   but let's just start with that.

I can't be bothered to eliminate the forward references:

.
|-- assigned
|   |-- asuffield
|   |   `-- 5.qux
|   |       `-- summary
|   `-- asuffield2
|-- closed
|   |-- done
|   |   `-- merge-asuffield-1
|   |       |-- merge-asuffield-1
|   |       |   |-- 1.foo-bar
|   |       |   |   `-- summary
|   |       |   |-- 2.foo-baz
|   |       |   |   `-- summary
|   |       |   `-- request
|   |       `-- request
|   `-- rejected
|-- etc
|   |-- central-tree
|   |-- email-addresses
|   |-- email-addresses~
|   `-- next-serial
|-- incoming
|   `-- 3.foo-bar
|       `-- summary
|-- new
|   `-- bad-bug
|       `-- summary
|-- pending
|   |-- asuffield
|   |   |-- merge-asuffield-2
|   |   |   `-- request
|   |   |-- merge-asuffield-3
|   |   |   `-- request
|   |   |-- merge-asuffield-4
|   |   |   |-- 4.quux
|   |   |   |   `-- summary
|   |   |   `-- request
|   |   `-- next-serial
|   `-- asuffield2
|       |-- merge-destination
|       `-- next-serial
|-- queue
|-- tools
`-- {arch}

(This isn't very poplated; it's just a pruned copy of what I've got on
hand)

Top-level directories are named based on the state of the bugs
contained within them.

>   The bug tree will be maintained by the bug masters, with the
>   gatekeepers and coders having their own copies in a star-topology to
>   the bug master's main tree.

In addition, one tree is designated as central. All branches will
reference it in etc/central-tree. Some changes may only occur in the
central tree; these will be indicated when they appear.

> * Bug and Patch Flow
> 
> ** New Bugs
> 
>   When someone reports a bug on gnu-arch-users, it is up to the 
>   bug masters to add it to the bug tree.
> 
>   Intially, they should format it suitably, assign it a name, and
>   if nothing else, add it to "incoming" subtree.

s/incoming/new/

In the central tree, all valid bugs in "new" are assigned serial
numbers and moved into "incoming". (This allows for disconnected bug
creation). Bugs which are in "new" are unique in that they don't have
serial numbers; their directory only has a name. While it is possible
for multiple bugs to have the same name, they can't be in new at the
same time.

Normally, bugs are either created directly in the central tree and
moved directly to incoming, or they are moved to incoming as soon as
they are merged into the central tree.

Only newly created bugs may be added to new. Existing bugs can never
be moved back into new once they have left it.

>   Periodically, the bug masters can post a summary of recent additions
>   to "incoming" to gnu-arch-dev and gnu-arch-users with the string
>   "[NEW BUGS]" in the subject line.
> 
> 
> ** Bug Queue
> 
>   It is up to the bug masters, in consultation with the user community
>   and the players, to schedule bug fixes.
> 
>   Mechanically, they do this by moving the bug from "incoming" to
>   "queue".   Files in "queue" get a numeric prefix -- assigned in the
>   order in which bugs arrive.

The number is now assigned when bugs enter incoming. The transition
from incoming to queue is a simple move.

>   Periodically, the bug masters can post a summary of recent additions
>   to the queue to gnu-arch-dev and gnu-arch-users with the string
>   "[BUG PRIORITIES]" in the subject line.
> 
>   A rough goal is to keep the size of the bug queue equal to the
>   number of gatekeeper players multiplied by 20.   If there are 
>   more outstanding bugs than that, some should sit in "incoming".
> 
>   Gatekeepers are permitted to move a bug from "queue" back to
>   "incoming" -- stripping away the assigned number.  When that
>   happens, the number that was assigned to the bug should not be
>   reused.   If the bug later goes back from "incoming" to "queue" it
>   gets a new number.  (One reason this might happen is if a newly
>   arrived bug is more important than some that are in the queue.)

Serial numbers are never removed. Bugs can transition back to incoming
from anywhere other than new at any time.

> ** Bug Assignments
> 
>   The goal is to give each gatekeeper a list of 10 bugs which are the
>   bugs owned by that gatekeeper.   These are the bugs the gatekeeper
>   should be working on or working with a coder to fix.
> 
>   Periodically, when a gatekeeper has fewer than 10 bugs, the bug
>   masters should post a message to the gnu-arch-dev list with the
>   string "[PICK BUGS <name>]" where "<name>" is the name of the 
>   gatekeeper.   The body of the message should include a summary of
>   the bug queue.
> 
>   The gatekeeper should reply, changing the subject line to "[PICKED
>   BUGS <name>]", with a list of bug names for bugs that gatekeeper
>   agrees to own.   The bug masters should then move those bugs from
>   the "queue" directory to appropriate "owned" subdirectory.
> 
>   Note that moving bugs from "queue" to "owned" may trigger a
>   condition in which an equal number of bugs should be moved
>   from "incoming" to "queue".

s/owned/assigned/

> ** Bug Reminders
> 
>   Periodically (and somewhat frequently) the bug masters should post
>   to the gnu-arch-dev list messages with subject lines "[REMINDER
>   <name>]" containing summaries of the bugs owned by gatekeeper
>   "<name>".
> 
> 
> ** Recording the Gatekeeper Tree
> 
>   The bug tree should contain a directory structure like this:
> 
>         ./gatekeepers/
>           ./gatekeepers/<name1>/
>             ./gatekeepers/<name2>/
>             ./gatekeepers/<name3>/
>             ./gatekeepers/<name4>/
>               ./gatekeepers/<name4>/<name5>
>          ...

s/gatekeepers/pending/

>   In other words, a tree of directories reflecting the tree of
>   gatekeepers.  Patch flow between gatekeepers in this example is
>   along the edges in the graph of:
> 
>                 <name1>
> 
>              /     |       \
>         <name2> <name3>    <name4>
>                               |
>                            <name5>

There is no nesting under pending/; every gatekeeper has precisely one
directory under pending/. This is a result of observing that there is
no DAG of patch flow in tla, so this heirarchy would require some
people to have multiple directories, which would be confusing. In
addition, the bug tracking stuff doesn't actually need to know this
(see below, merge confirmations).

> ** Merge Requests
> 
>   A gatekeeper who is not the root node can post a message to
>   gnu-arch-dev with the subject line "[MERGE-REQUEST <name>]"
>   where <name> is the gatekeeper posting the request.

<name> is the gatekeeper who needs to perform the merge. The From line
of the message is examined to find the person posting the request.

> 
>   The merge request should contain:
> 

>         The name and location of the archive to merge from.
> 
>         The version and, if applicable, the revisions to merge
>         from.

Deferred. There should be something like configurations that describes
merge operations, and that should be included in the merge
request. For now, this should be included in the body of the message
as a simple description.

>         A list of bug names closed by the merge.  (This may, of
>         course, be empty.   If empty, the message should instead 
>         contain a description of what is in the merge.)

A merge request has a pseudo-header. The pseudo-header has
approximately the same syntax as an rfc822 header, and is placed at
the start of the body, and separated from the real body by a blank
line. The pseudo-header is optional.

The following fields are defined:

 Bug: a number, or a number and name formatted like the directory name
      of the bug. This is a prefix match. It indicates that the bug is
      closed by the merge.
 Merge: the name of a merge assigned to the sender, which is being
      passed up to a higher gatekeeper. This automatically includes
      all the bugs closed by the given merge; they don't need to be
      specified separately. The merge- prefix is optional.

If no pseudo-header is present, there are assumed to be no bugs or
merges attached to this request.

>   Bug masters should respond by
> 
>         1. Adding a directory "merge-<name>-<n>" to the gatekeeper 
>            directory of the gatekeeper who needs to perform
>            the merge.  Within that directory, the file "=request"
>            should contain the "[MERGE-REQUEST ...]" post.

s/=request/request/

With every bug having a numeric prefix, there are no namespace issues.

The file 'log' contains a history formatted like the bug log,
describing every operation on the merge request.

Likewise for 'mbox'.

The number is unique for the current gatekeeper, but not globally
unique.

>         2. Moving the bug file from the requestors "owned" directory
>            to the "merge-<name>-<n>" directory alongside the merge
>            request.

s/bug file/bug directory/

>   Periodically, the bug masters should post a message to gnu-arch-dev
>   with the subject "[PENDING MERGES <name>]" where "<name>" is the
>   name of the gatekeeper who needs to make the merge. It should
>   summarize the contents of the "merge-<name>-<n>" directories for
>   that gatekeeper.
> 
>   For example, it might look like:
> 
>         request-name: rbcollins-3
>         archive: ...
>         location: ...
>         version: ...
>         revisions: ....
>         bugs: some-bug-k, some-bug-q
> 
>                 * some-bug-k
>                   <bug "subject:" of some-bug-k>
>                 * some-bug-q
>                   <bug "subject:" of some-bug-q>
> 
> 
> 
>         request-name: jblack-5
>         archive: ...
>         location: ...
>         version: ...
>         revisions: ....
>         bugs: some-bug-r
> 
>                 * some-bug-r
>                   <bug "subject:" of some-bug-r>
> 
> 
>         ...
> 
> 
> ** Merge Confirmations
> 
>   A gatekeeper with pending merge requests can post a message to
>   gnu-arch-dev of the form "[MERGED <name>-<N>]" to indicate that
>   that merge has been performed.
> 
>   If the gatekeeper making that post is the root node, then the bugs
>   stored in the "merge-<name>-<N>" directory should be moved to the
>   "closed" directory (by the bug masters) and the "merge-<name>-<N>" 
>   directory deleted.

merge directories are never deleted, although they may be
rejected. Bugs are only removed from a merge directory if they are not
fixed by the merge; when a merge is performed, the entire merge-*
directory is moved elsewhere, and kept intact.

If the file pending/<name>/merge-destination exists then it contains a
single word, which is the name of the directory under closed/ to which
the merge is moved. If the file contains 'done', then the merge
directory is moved into closed/done/.

>   If the gatekeeper making that post is _not_ the root node, then 
>   the bug files in the "merge-<name>-<N>" directory should be moved
>   to the "owned" directory for that gatekeeper and the
>   "merge-<name>-<N>" directory removed.   Note that this can result in
>   the gatekeeper in question owning more than 10 bugs.

If the file does not exist, then the merge directory is moved into
assigned/<name>/. This indicates that the gatekeeper is responsible
for creating a merge request for somebody else to pick up the same
merge; this is done with the Merge pseudo-header.

When merges pass through multiple gatekeepers, a deeply nested tree
will be formed:
pending/name1/merge-name2-4/merge-name3-6/

Bugs may be present at any depth. The set of bugs associated with the
merge is all of those contained in the tree; bugs aren't normally
moved up to higher directories.

This idiom:
pending/name1/merge-name1-8/

Is a personal todo list entry (request from self to self, to merge
something that's in a different branch).

> ** Bug Rejection
> 
>   A gatekeeper may post a message to gnu-arch-dev with the subject
>   "[REJECT <bug>]".  The body of the message should explain.
> 
>   If the indicated bug is in "incoming", "queue", or the "owned"
>   directory for that gatekeeper, the bug masters should move the bug
>   to the "rejected" directory.   Ideally they should add the rejection
>   description to the bug.

closed/rejected/ directory.

>   Otherwise, the bug masters should reply to the list that the REJECT
>   request is invalid.
> 
>   Periodically, the bug masters should post to both gnu-arch-users and
>   gnu-arch-dev a list of recently rejected bugs.
> 
> 
> * What are "coders"?
> 
>   The rules above talk about gatekeepers and bug masters but don't say
>   anything about coders.   So, what are coders?
> 
>   Coders follow all of the same rules as gatekeepers -- but with a 
>   couple of exceptions:
> 
>   a) In the gatekeeper tree, coders may only be leaf nodes.
> 
>   b) The bug masters do not try to maintain a condition that coders 
>      have a list of 10 owned bugs.
> 
>   c) Coders may not directly post PICKED-BUGS messages.   Instead,
>      their (gatekeeper) parent in the gatekeeper tree can post one
>      on their behalf.
> 
>   Periodically, the bug masters should post messages with subject
>   lines containing "[MANAGING <name>]" where <name> is the name of
>   a gatekeeper.   That message should list the coders who are
>   subordinate to that gatekeeper, any bugs they have pending, and the
>   date on which the bug was assigned to that coder.

Deferred. Can't think of anything useful to do with this
information, so it can wait until somebody needs it (that will
probably define what data exactly is needed).

> * Extensions
> 
>   Aside from automation:
> 
>   ~ web pages describing the status of the game

Duplicate at least bugreport.cgi from debbugs, and something similar
for merges. Create a parallel to pkgreport.cgi that shows all bugs
assigned to a given gatekeeper.

>   ~ ways to "link" two instances of the game for a related project.
> 
>     For example, if some GNU/Hurd distribution maintainer were to
>     set up an instance of this game for a particular package (package
>     XYZZY), and meanwhile the upstream maintainer of XYZZY also has
>     an instance of the game -- how can they be linked together?

Aside from defining a globally unique identifier for bugs, deferred
until somebody can define what "linked" means.


A mail interface to tools/punt-bug will be provided, which moves any
bug back to incoming. All the other things in tools/ correspond to the
mail interface described above.

-- 
  .''`.  ** Debian GNU/Linux ** | Andrew Suffield
 : :' :  http://www.debian.org/ |
 `. `'                          |
   `-             -><-          |

signature.asc
Description: Digital signature