[[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
# Experimental Tag Sharing / Pseudo-Bug-Tracking for/with notmuch
## Web View
There is a dump of (some views of) the nmbug [[status|https://nmbug.notmuchmail.org/status]].
## Getting started
0. Make sure that the whole [notmuch@notmuchmail.org mailing list
archive][archive] is available in your email database.
If you are missing messages which are tagged in the nmbug
repository, `nmbug status` will complain with U-prefixed lines and
you will have to jump through some hoops to create commits that
alter tags for those messages. Most other nmbug operation will be
unaffected.
1. Install and use nmbug from notmuch version **0.19** or newer, and
either Python 2.7 or anything from the 3.x line.
The nmbug script is available in [devel/nmbug][nmbug].
2. Make sure your `git version` is **1.7.4** or newer.
3. Enter the following command to obtain the current tag repository:
`$ nmbug clone https://nmbug.notmuchmail.org/git/nmbug-tags.git`
4. Clobber your local `notmuch::…` tag namespace with:
`$ nmbug checkout`
Without this, `nmbug status` will list all of the upstream tags as
deleted (with the D prefix).
## 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.notmuchmail.org: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 push URL with:
$ git --git-dir=$HOME/.nmbug remote set-url --push origin nmbug@nmbug.notmuchmail.org: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::patch and not tag:notmuch::needs-review and not \
tag:notmuch::pushed and not tag:notmuch::obsolete and not \
tag:notmuch::wontfix and not tag:notmuch::moreinfo and not \
tag:notmuch::stale and not tag:notmuch::wip
See the [[status|https://nmbug.notmuchmail.org/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
extract 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
- Currently the parser of nmbug (like that of notmuch restore) assumes
that there are no spaces in message-ids.
[archive]: https://nmbug.notmuchmail.org/archive/notmuch-list.tar.xz
[nmbug]: https://git.notmuchmail.org/git/notmuch/blob/HEAD:/devel/nmbug/nmbug
|
