notmuch/

Experimental Tag Sharing / Pseudo-Bug-Tracking for/with notmuch

Web View

There is a dump of (some views of) the nmbug status.

Getting started

  1. Install and use notmuch version 0.10 or newer and perl module Pod::Usage (packaged as perl-doc in debian).

    The nmbug script is available in contrib/nmbug.

  2. Make sure your git version is 1.7.4 or newer.

  3. Enter the following command to obtain the current tag repository:

    $ git clone --bare http://nmbug.tethera.net/git/nmbug-tags.git $HOME/.nmbug

Using nmbug, simple example

# get the latest version of the tags
$ nmbug pull

# do some tagging; see below for conventions
$ notmuch tag +notmuch::patch $id

# write the tag changes from the notmuch database
$ nmbug commit

Using nmbug, doing the same thing with more steps

# get the latest version of the tags
$ nmbug fetch

# Optionally inspect the fetched changes

$ nmbug status
 a   tags/id1/patch
 d   tags/id2/pushed

# merge the fetched tags into notmuch
$ nmbug merge

# observe status is clear now,
$ nmbug status

# make the tag changes
$ notmuch tag +notmuch::patch id

# double check your changes
$ nmbug status
A tags/id/patch

# write the tag changes
$ nmbug commit

Submitting tags

For the moment, we are using a central repo, hosted at:

nmbug@nmbug.tethera.net:nmbug-tags

To get push access, send your public key (ideally in a gpg signed email) to David Bremner. There is a convenience command:

$ nmbug push

But you will have to change your url with:

$ git --git-dir=$HOME/.nmbug remote set-url origin nmbug@nmbug.tethera.net:nmbug-tags

Tagging conventions

Note that the tag database is probably catching up to these conventions.

Main patch tracking tags

Initially any patch should be tagged:

notmuch::patch

Patches that are for discussion, rather than proposed for master should also be tagged:

notmuch::wip                is "work in progress", posted for review or comment.

Most patches will be initially tagged:

notmuch::needs-review       needs some (more) review

unless they are tagged:

notmuch::trivial            looks harmless

Patches keep notmuch::needs-review until they either get enough reviews, or one of the following resolutions is reached:

notmuch::obsolete           replaced by some other patch
notmuch::pushed             is pushed to master
notmuch::wontfix            for whatever reason, this patch will not
                            be applied

Sometimes the process stalls, and patches get tagged:

notmuch::moreinfo           waiting for feedback from patch proposer
                            or others
notmuch::stale              The patch no longer applies to master (or in
                            rare cases, to release)

Note that these tags typically apply to whole series of patches; it doesn't usually make sense to apply patches later in the series before earlier ones. So a patch may be tagged moreinfo or stale only because a predecessor patch is.

Bug tracking tag

So far we are just tagging certain messages as bug reports, meaning things that "everyone" agrees should be fixed.

notmuch::bug                is a bug report
notmuch::fixed              indicates that the bug is fixed in the
                            master branch

Optional tags

These patches are more comments and suggestions.

notmuch::doc                is a documentation patch
notmuch::emacs              is a patch/bug for the emacs UI
notmuch::feature            provides a new feature
notmuch::fix                fixes a bug
notmuch::portability        improves portability
notmuch::review             is a review
notmuch::test               provides a new test/or improves testing
notmuch::$n                 this patch should be considered for
                            release $n

Tracking the patch queue

I (David Bremner) use the following search (in my case as a saved search in emacs):

tag:notmuch::patch and not tag:notmuch::pushed and \
    not tag:notmuch::obsolete and not tag:notmuch::wip \
        and not tag:notmuch::moreinfo and not tag:notmuch::contrib

You might or might not want as many exclusions. Another interesting search is:

tag:notmuch::reviewed and not tag:notmuch::pushed

See the status page for more example searches.

Design notes

Disk format

The tags are stored in a bare-repo, which means they are not obviously visible. There is an nmbug archive command analogous to git archive Tags are represented as empty files in the tree; if you extra them, the tree looks something like:

tags/878waiwi0f.wl%25james@hackervisions.org/
tags/878waiwi0f.wl%25james@hackervisions.org/emacs
tags/878waiwi0f.wl%25james@hackervisions.org/patch
tags/87aa8j7hqu.fsf@zancas.localnet/
tags/87aa8j7hqu.fsf@zancas.localnet/patch
tags/87aa8j7hqu.fsf@zancas.localnet/pushed

The %25 represents hex code for a character that cannot be used directly (in this case %, only because it is needed as an escape).

Assumptions