1 # Experimental Tag Sharing / Pseudo-Bug-Tracking for/with notmuch
5 There is a dump of (some views of) the nmbug [[status|http://nmbug.tethera.net/status]].
9 1. Install and use notmuch version notmuch 0.9+63~gebd1adc or newer and
10 perl module `Pod::Usage` (packaged as `perl-doc` in debian).
12 The nmbug script is available in `contrib/nmbug`.
14 2. The current tag repo can be obtained by:
16 `$ git clone --bare http://nmbug.tethera.net/git/nmbug-tags.git $HOME/.nmbug`
18 Check that your git is recent enough by entering:
20 `$ git --git-dir=$HOME/.nmbug fetch`
22 If you get failures then you need to update your git (as well).
24 ## Using nmbug, simple example
26 # get the latest version of the tags
29 # do some tagging; see below for conventions
30 $ notmuch tag +notmuch::patch $id
32 # write the tag changes from the notmuch database
35 ## Using nmbug, doing the same thing with more steps
37 # get the latest version of the tags
40 # Optionally inspect the fetched changes
46 # merge the fetched tags into notmuch
49 # observe status is clear now,
52 # make the tag changes
53 $ notmuch tag +notmuch::patch id
55 # double check your changes
59 # write the tag changes
64 For the moment, we are using a central repo, hosted at:
66 nmbug@nmbug.tethera.net:nmbug-tags
68 To get push access, send your public key (ideally in a gpg signed
69 email) to David Bremner. There is a convenience command:
73 But you will have to change your url with:
75 $ git --git-dir=$HOME/.nmbug remote set-url origin nmbug@nmbug.tethera.net:nmbug-tags
77 ## Tagging conventions
79 _Note that the tag database is probably catching up to these
82 ### Main patch tracking tags
84 Initially any patch should be tagged:
88 Patches that are for discussion, rather than proposed for master should be tagged:
90 notmuch::wip is "work in progress", posted for review or comment.
92 Most patches will be initially tagged:
94 notmuch::needs-review needs some (more) review
96 unless they are tagged:
98 notmuch::trivial looks harmless
100 Patches keep `notmuch::needs-review` until they either get enough
101 reviews, or one of the following resolutions is reached:
103 notmuch::obsolete replaced by some other patch
104 notmuch::pushed is pushed to master
105 notmuch::wontfix for whatever reason, this patch will not
108 Sometimes the process stalls, and patches get tagged:
110 notmuch::moreinfo waiting for feedback from patch proposer
112 notmuch::stale The patch no longer applies to master (or in
113 rare cases, to release)
116 So far we are just tagging certain messages as bug reports, meaning
117 things that "everyone" agrees should be fixed.
119 notmuch::bug is a bug report
120 notmuch::fixed indicates that the bug is fixed in the
125 These patches are more comments and suggestions.
127 notmuch::doc is a documentation patch
128 notmuch::emacs is a patch/bug for the emacs UI
129 notmuch::feature provides a new feature
130 notmuch::fix fixes a bug
131 notmuch::portability improves portability
132 notmuch::review is a review
133 notmuch::test provides a new test/or improves testing
134 notmuch::$n this patch should be considered for
137 ## Tracking the patch queue
139 I (David Bremner) use the following search (in my case as a saved
142 tag:notmuch::patch and not tag:notmuch::pushed and \
143 not tag:notmuch::obsolete and not tag:notmuch::wip \
144 and not tag:notmuch::moreinfo and not tag:notmuch::contrib
146 You might or might not want as many exclusions. Another interesting
149 tag:notmuch::reviewed and not tag:notmuch::pushed
155 The tags are stored in a bare-repo, which means they are not obviously
156 visible. There is an `nmbug archive` command analogous to `git
157 archive` Tags are represented as empty files in the tree; if you extra
158 them, the tree looks something like:
160 tags/878waiwi0f.wl%25james@hackervisions.org/
161 tags/878waiwi0f.wl%25james@hackervisions.org/emacs
162 tags/878waiwi0f.wl%25james@hackervisions.org/patch
163 tags/87aa8j7hqu.fsf@zancas.localnet/
164 tags/87aa8j7hqu.fsf@zancas.localnet/patch
165 tags/87aa8j7hqu.fsf@zancas.localnet/pushed
167 The `%25` represents hex code for a character that cannot be used directly
168 (in this case %, only because it is needed as an escape).
172 - Currently the parser of nmbug (like that of notmuch restore) assumes
173 that there are no spaces in message-ids.