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
89 should also be tagged:
91 notmuch::wip is "work in progress", posted for review or comment.
93 Most patches will be initially tagged:
95 notmuch::needs-review needs some (more) review
97 unless they are tagged:
99 notmuch::trivial looks harmless
101 Patches keep `notmuch::needs-review` until they either get enough
102 reviews, or one of the following resolutions is reached:
104 notmuch::obsolete replaced by some other patch
105 notmuch::pushed is pushed to master
106 notmuch::wontfix for whatever reason, this patch will not
109 Sometimes the process stalls, and patches get tagged:
111 notmuch::moreinfo waiting for feedback from patch proposer
113 notmuch::stale The patch no longer applies to master (or in
114 rare cases, to release)
117 So far we are just tagging certain messages as bug reports, meaning
118 things that "everyone" agrees should be fixed.
120 notmuch::bug is a bug report
121 notmuch::fixed indicates that the bug is fixed in the
126 These patches are more comments and suggestions.
128 notmuch::doc is a documentation patch
129 notmuch::emacs is a patch/bug for the emacs UI
130 notmuch::feature provides a new feature
131 notmuch::fix fixes a bug
132 notmuch::portability improves portability
133 notmuch::review is a review
134 notmuch::test provides a new test/or improves testing
135 notmuch::$n this patch should be considered for
138 ## Tracking the patch queue
140 I (David Bremner) use the following search (in my case as a saved
143 tag:notmuch::patch and not tag:notmuch::pushed and \
144 not tag:notmuch::obsolete and not tag:notmuch::wip \
145 and not tag:notmuch::moreinfo and not tag:notmuch::contrib
147 You might or might not want as many exclusions. Another interesting
150 tag:notmuch::reviewed and not tag:notmuch::pushed
152 See the [[status|http://nmbug.tethera.net/status]] page for more
159 The tags are stored in a bare-repo, which means they are not obviously
160 visible. There is an `nmbug archive` command analogous to `git
161 archive` Tags are represented as empty files in the tree; if you extra
162 them, the tree looks something like:
164 tags/878waiwi0f.wl%25james@hackervisions.org/
165 tags/878waiwi0f.wl%25james@hackervisions.org/emacs
166 tags/878waiwi0f.wl%25james@hackervisions.org/patch
167 tags/87aa8j7hqu.fsf@zancas.localnet/
168 tags/87aa8j7hqu.fsf@zancas.localnet/patch
169 tags/87aa8j7hqu.fsf@zancas.localnet/pushed
171 The `%25` represents hex code for a character that cannot be used directly
172 (in this case %, only because it is needed as an escape).
176 - Currently the parser of nmbug (like that of notmuch restore) assumes
177 that there are no spaces in message-ids.