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 notmuch 0.9+63~gebd1adc or newer and perl module Pod::Usage (packaged as perl-doc in debian).

    The nmbug script is available in contrib/nmbug.

  2. The current tag repo can be obtained by:

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

    Check that your git is recent enough by entering:

    $ git --git-dir=$HOME/.nmbug fetch

    If you get failures then you need to update your git (as well).

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

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

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