1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
2 # Experimental Tag Sharing / Pseudo-Bug-Tracking for/with notmuch
6 There is a dump of (some views of) the nmbug [[status|https://nmbug.notmuchmail.org/status]].
10 0. Make sure that the whole [notmuch@notmuchmail.org mailing list
11 archive][archive] is available in your email database.
13 If you are missing messages which are tagged in the nmbug
14 repository, `nmbug status` will complain with U-prefixed lines and
15 you will have to jump through some hoops to create commits that
16 alter tags for those messages. Most other nmbug operation will be
19 1. Install and use nmbug from notmuch version **0.19** or newer, and
20 either Python 2.7 or anything from the 3.x line.
22 The nmbug script is available in [devel/nmbug][nmbug].
24 2. Make sure your `git version` is **1.7.4** or newer.
26 3. Enter the following command to obtain the current tag repository:
28 `$ nmbug clone https://nmbug.notmuchmail.org/git/nmbug-tags.git`
30 4. Clobber your local `notmuch::…` tag namespace with:
34 Without this, `nmbug status` will list all of the upstream tags as
35 deleted (with the D prefix).
37 ## Using nmbug, simple example
39 # get the latest version of the tags
42 # do some tagging; see below for conventions
43 $ notmuch tag +notmuch::patch $id
45 # write the tag changes from the notmuch database
48 ## Using nmbug, doing the same thing with more steps
50 # get the latest version of the tags
53 # Optionally inspect the fetched changes
59 # merge the fetched tags into notmuch
62 # observe status is clear now,
65 # make the tag changes
66 $ notmuch tag +notmuch::patch id
68 # double check your changes
72 # write the tag changes
77 For the moment, we are using a central repo, hosted at:
79 nmbug@nmbug.notmuchmail.org:nmbug-tags
81 To get push access, send your public key (ideally in a gpg signed
82 email) to David Bremner. There is a convenience command:
86 But you will have to change your push URL with:
88 $ git --git-dir=$HOME/.nmbug remote set-url --push origin nmbug@nmbug.notmuchmail.org:nmbug-tags
90 ## Tagging conventions
92 _Note that the tag database is probably catching up to these
95 ### Main patch tracking tags
97 Initially any patch should be tagged:
101 Patches that are for discussion, rather than proposed for master
102 should also be tagged:
104 notmuch::wip is "work in progress", posted for review or comment.
106 Most patches will be initially tagged:
108 notmuch::needs-review needs some (more) review
110 unless they are tagged:
112 notmuch::trivial looks harmless
114 Patches keep `notmuch::needs-review` until they either get enough
115 reviews, or one of the following resolutions is reached:
117 notmuch::obsolete replaced by some other patch
118 notmuch::pushed is pushed to master
119 notmuch::wontfix for whatever reason, this patch will not
122 Sometimes the process stalls, and patches get tagged:
124 notmuch::moreinfo waiting for feedback from patch proposer
126 notmuch::stale The patch no longer applies to master (or in
127 rare cases, to release)
129 Note that these tags typically apply to whole series of patches; it
130 doesn't usually make sense to apply patches later in the series before
131 earlier ones. So a patch may be tagged `moreinfo` or `stale` only
132 because a predecessor patch is.
136 So far we are just tagging certain messages as bug reports, meaning
137 things that "everyone" agrees should be fixed.
139 notmuch::bug is a bug report
140 notmuch::fixed indicates that the bug is fixed in the
145 These patches are more comments and suggestions.
147 notmuch::doc is a documentation patch
148 notmuch::emacs is a patch/bug for the emacs UI
149 notmuch::feature provides a new feature
150 notmuch::fix fixes a bug
151 notmuch::portability improves portability
152 notmuch::review is a review
153 notmuch::test provides a new test/or improves testing
154 notmuch::$n this patch should be considered for
157 ## Tracking the patch queue
159 I (David Bremner) use the following search (in my case as a saved
162 tag:notmuch::patch and not tag:notmuch::pushed and \
163 not tag:notmuch::obsolete and not tag:notmuch::wip \
164 and not tag:notmuch::moreinfo and not tag:notmuch::contrib
166 You might or might not want as many exclusions. Another interesting
169 tag:notmuch::patch and not tag:notmuch::needs-review and not \
170 tag:notmuch::pushed and not tag:notmuch::obsolete and not \
171 tag:notmuch::wontfix and not tag:notmuch::moreinfo and not \
172 tag:notmuch::stale and not tag:notmuch::wip
174 See the [[status|https://nmbug.notmuchmail.org/status]] page for more
181 The tags are stored in a bare-repo, which means they are not obviously
182 visible. There is an `nmbug archive` command analogous to `git
183 archive` Tags are represented as empty files in the tree; if you
184 extract them, the tree looks something like:
186 tags/878waiwi0f.wl%25james@hackervisions.org/
187 tags/878waiwi0f.wl%25james@hackervisions.org/emacs
188 tags/878waiwi0f.wl%25james@hackervisions.org/patch
189 tags/87aa8j7hqu.fsf@zancas.localnet/
190 tags/87aa8j7hqu.fsf@zancas.localnet/patch
191 tags/87aa8j7hqu.fsf@zancas.localnet/pushed
193 The `%25` represents hex code for a character that cannot be used directly
194 (in this case %, only because it is needed as an escape).
198 - Currently the parser of nmbug (like that of notmuch restore) assumes
199 that there are no spaces in message-ids.
201 [archive]: https://nmbug.notmuchmail.org/archive/notmuch-list.tar.xz
202 [nmbug]: https://git.notmuchmail.org/git/notmuch/blob/HEAD:/devel/nmbug/nmbug