[darcs-users] the darcs.net patch tracker

[Eric Kow]

Hi everybody,

As I mentioned earlier, the Darcs Team just grew a small piece of
infrastructure.

Objectives
----------
I want to make it easy to

1. see at a glance what the open patches are, who's assigned to
   them if any and how stale they are
2. see at a glance what patches are assigned to *me*

Same email-centric workflow as before
-------------------------------------
The patch tracker is meant to complement the pre-existing email-centric
workflow:

 1. hacker darcs sends patches over email
 2. a new message appears on darcs-users
 3. a reviewer reviews the patch on the list and pushes it

You can pretty much forget that the patch tracker exists.
Okay, so what are the changes to the workflow exactly?

 1b. Instead of sending patches to darcs-users at darcs.net, people
     send patches to patches at darcs.net.
     
     This change should happen automatically because I've updated
     _darcs/prefs/email in the main repository.  Note that users
     who, for whatever reason, cannot use darcs send must make
     sure their message either begins with 'darcs patch:' or with
     '[patch]'

 2b. When the patch arrives on darcs-users, the subject line starts
     with [patchNNNN] instead of 'darcs patch:' (this is done by
     some procmail and sed)

 3b. For the patch manager's convenience (not that we have a
     patch manager anymore), the reviewer could bcc the patch
     tracker and add some metadata to update its state (see
     below).

Using the patch tracker
-----------------------
The patch tracker is now part of the general darcs issue tracker.

* To see a list of unassigned patches: click on 'Show Unassigned'
  in the left hand sidebar.  If you're looking for a patch to
  review, this is the place to go, for these are patches that are
  not yet assigned to anybody

* To see a list of patches assigned to you: click on 'Your Patches'
  in the left hand sidebar.  You may also be interested in
  'Your Issues'

* To update the status of a patch; the most convenient way is to
   - bcc: patches at darcs.net
   - add to the Subject: [status=FOO] where FOO can be
     * review-in-progress
     * amend-requested
     * obsoleted
     * rejected
     * accepted
   You can also use the web interface to do this

* To view a specific patch:
    http://bugs.darcs.net/patch42

Some general notes: Bugs and patches have slightly different UIs (for
example, patches have statuses like 'needs-review').  They can also
refer to each other fairly seamlessly (patches have a field specifically
to point to related issues; issues don't have such a field yet, but if
you say 'patch42' in a message, roundup will automatically create a
hyperlink to that patch).

I've attached a quick little screenshot showing the main queries.

Known flaws: try and see first
------------------------------
There are two things which some darcs hackers may view as shortcomings
to the patch tracker

* Reviewing patches on the tracker is not easy; you can't view the
  patch inline (this is an unintentional flaw) and you cannot
  conveniently reply to patches (this is partly deliberate)

* You cannot easily view the discussion on the patch tracker.
  Right now the workaround is to visit the mailing list (the web
  UI has a link to the archives).

I realise that this may not be what everybody is hoping for, but I would
like everybody to take an "try and see" attitude to this.

First, maybe these apparent shortcomings actually aren't so bad in
practice.

Second, there is a chance that we'll be able to address some of the
issues with a little more automation via DarcsWatch.  So they may not
even be worth arguing for because they could just be solved in an
unexpected way.

Third, aside from the sheer practical matter that these things take a
lot of time/effort to implement, I'm a little leery of some of the
hidden costs behind these features.  I'm open to discussing this in
greater detail, and I expect to be wrong about many things here; but
I would like to have some practical experience first to deeply
understand why I'm wrong and what I can do about it.

So let's all get some concrete firsthand experience using the patch
tracker and revisit the issue after the dust from the hacking sprint
settles.

Other known flaws
-----------------
Aside from the issues above, there are lots of little flaws and holes
that we'll need to patch up over time.  Here's the list of issues off
the top of my head.

- Reply to says "Darcs bug tracker" (which looks weird)

- There is no automatically generated link from the patch tracker to
  the email thread about a patch

- Not yet implemented
  - web form to submit a new patch
  - general patch search form
  - canned query for patches submitted by you

More notes welcome!  Meanwhile, thanks to Jason for making sure we don't
forget this idea, to Simon for all the roundup help and to the roundup
team for the simple versatility of their product.

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
PGP Key ID: 08AC04F9
-------------- next part --------------
A non-text attachment was scrubbed...
Name: patch-tracker-screenshot.png
Type: image/png
Size: 168535 bytes
Desc: not available
URL: <http://lists.osuosl.org/pipermail/darcs-users/attachments/20091027/a5d820e7/attachment-0001.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: Digital signature
URL: <http://lists.osuosl.org/pipermail/darcs-users/attachments/20091027/a5d820e7/attachment-0001.pgp>