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

[Tom Lord]

Over the past two months the rate of code contributions and bug
reports/feature requests to arch seems to have increased noticably.

Among those contributions have been two examples of people making
'integration branches' -- esentially offloading some review and
merging work from me.   So far we've handled this very informally:
catch as catch can.

Meanwhile, the savannah bug tracker has become a serious bottleneck
for me.   I could try to imagine a less convenient, slower interface
to issue tracking -- but it would be a struggle.

I'd like to propose a game and see if any volunteers would like to
join me in playing it.  The purpose of the game is to help "scale" the
arch project -- to facilitate more rapid incorporation of
contributions and higher-quality releases (not that we've been doing
too bad on either front :-).

I should say at the outset that I won't be too surprised if we don't
get enough players.  I think we'd need 3 minimum -- 6 would be great
-- but playing this game would be a larger commitment than the
ordinary voluntary contribution to the project.

Along those lines, I'd also like to invite corporate users (or
corporate evaluators) of arch to pipe up (off-list if you like) if you
think you might want to experiment by helping to monetize this game.

The initial rules of the game are given below (subject to revision
based on other people's ideas or experience as the game unfolds).

You have to forgive me that the rules are kind of long but, really,
it's a pretty simple game.  _If_ we get some players and _if_ the game
proves winning -- a lot of the "bookkeeping" for it can be automated.
Who knows?  Maybe this will turn into a "project management toolkit."


* Equipment:

  the address@hidden mailing list

  a new address@hidden mailing list

  one archive per player containing branches of the trees 
   that comprise arch plus a new tree: the bug list


* Players:

  the bug masters (a team of 1-3)
        Their job is to manage the bug list and
        the hacking agenda

  the gatekeepers (at least one)
        Their job is to prepare integration branches
        (merging and tweaking changes from other
        sources.)   Each bug that is "owned" is 
        owned by a gatekeeper -- the fix for that 
        bug is expected to show up in one of the
        integration branches of that gatekeeper.

        The gatekeepers form a tree with the root-node
        gatekeeper being the one who makes arch releases
        and maintains the project's tla--devo.   (Initially
        I'll be the root node gatekeeper but eventually 
        perhaps we should rotate it.)

  the coders (at least one :-)
        Their job is to actually write the changes
        that get merged into integration trees.
        If someone who is not officially a player
        submits a change, some coder or gatekeeper
        can take on that change in the role of "proxy".

  A single player can take on more than one of those roles.
  (Someone might be a gatekeeper and a coder;  or a coder
  and a bug master;  or all three; etc.)


* 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.

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

  Every bug will have a one-line "Subject:"

  Every bug will have a short summary -- ideally saying enough
  to fully describe the bug and any changeset contributed to fix
  it but at least containing the bug name.

  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.

  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 other words, star-merges will happen along the arrows in
  diagrams like:



            arch-bugs--lord--0.1
                   ^
                   |
                   v
            arch-bugs--masters--0.1 <-> arch-bugs--sally--0.1
                   ^
                   |
                   v
            arch-bugs--joe--0.1

   Mostly it will be up to the bug master to make changes to the 
   tree but gatekeepers and coders can make changes that the
   bug masters merge in.


* 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.

  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.

  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.)


** 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".


** 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>
         ...

  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>


** 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.

  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.

        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.)

  
  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.

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

  For example:

        BEFORE:

                owned/joe/000345.some-bug-X

        AFTER:

                gatekeepers/lord/merge-joe-4/
                  gatekeepers/lord/merge-joe-4/=request
                  gatekeepers/lord/merge-joe-4/000345.some-bug-X



  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.

  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.


** 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.

  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.


* Extensions

  Aside from automation:

  ~ web pages describing the status of the game

  ~ 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?



-t