Disambiguate Debian notmuch package and notmuch for emacs package.
[notmuch-wiki] / nmbug.mdwn
1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
2 # Experimental Tag Sharing / Pseudo-Bug-Tracking for/with notmuch
3
4 ## Web View
5
6 There is a dump of (some views of) the nmbug [[status|https://nmbug.notmuchmail.org/status]].
7
8 ## Getting started
9
10 0. Make sure that the whole [notmuch@notmuchmail.org mailing list
11    archive][archive] is available in your email database.
12
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
17    unaffected.
18
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.
21
22    The nmbug script is available in [devel/nmbug][nmbug].
23
24 2. Make sure your `git version` is **1.7.4** or newer. 
25
26 3. Enter the following command to obtain the current tag repository:
27
28    `$ nmbug clone https://nmbug.notmuchmail.org/git/nmbug-tags.git`
29
30 4. Clobber your local `notmuch::…` tag namespace with:
31
32    `$ nmbug checkout`
33
34    Without this, `nmbug status` will list all of the upstream tags as
35    deleted (with the D prefix).
36
37 ## Using nmbug, simple example
38
39     # get the latest version of the tags
40     $ nmbug pull
41
42     # do some tagging; see below for conventions
43     $ notmuch tag +notmuch::patch $id
44
45     # write the tag changes from the notmuch database
46     $ nmbug commit
47
48 ## Using nmbug, doing the same thing with more steps
49
50     # get the latest version of the tags
51     $ nmbug fetch
52
53     # Optionally inspect the fetched changes
54
55     $ nmbug status
56      a   tags/id1/patch
57      d   tags/id2/pushed
58
59     # merge the fetched tags into notmuch
60     $ nmbug merge
61
62     # observe status is clear now,
63     $ nmbug status
64
65     # make the tag changes
66     $ notmuch tag +notmuch::patch id
67
68     # double check your changes
69     $ nmbug status
70     A tags/id/patch
71
72     # write the tag changes
73     $ nmbug commit
74
75 ## Submitting tags
76
77 For the moment, we are using a central repo, hosted at:
78
79     nmbug@nmbug.notmuchmail.org:nmbug-tags
80
81 To get push access, send your public key (ideally in a gpg signed
82 email) to David Bremner.  There is a convenience command:
83
84     $ nmbug push
85
86 But you will have to change your push URL with:
87
88     $ git --git-dir=$HOME/.nmbug remote set-url --push origin nmbug@nmbug.notmuchmail.org:nmbug-tags
89
90 ## Tagging conventions
91
92 _Note that the tag database is probably catching up to these
93 conventions._
94
95 ### Main patch tracking tags
96
97 Initially any patch should be tagged:
98
99     notmuch::patch
100
101 Patches that are for discussion, rather than proposed for master
102 should also be tagged:
103
104     notmuch::wip                is "work in progress", posted for review or comment.
105
106 Most patches will be initially tagged:
107
108     notmuch::needs-review       needs some (more) review
109
110 unless they are tagged:
111
112     notmuch::trivial            looks harmless
113
114 Patches keep `notmuch::needs-review` until they either get enough
115 reviews, or one of the following resolutions is reached:
116
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
120                                 be applied
121
122 Sometimes the process stalls, and patches get tagged:
123
124     notmuch::moreinfo           waiting for feedback from patch proposer
125                                 or others
126     notmuch::stale              The patch no longer applies to master (or in
127                                 rare cases, to release)
128
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.
133
134 ### Bug tracking tag
135
136 So far we are just tagging certain messages as bug reports, meaning
137 things that "everyone" agrees should be fixed.
138
139     notmuch::bug                is a bug report
140     notmuch::fixed              indicates that the bug is fixed in the
141                                 master branch
142
143 ### Optional tags
144
145 These patches are more comments and suggestions.
146
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
155                                 release $n
156
157 ## Tracking the patch queue
158
159 I (David Bremner) use the following search (in my case as a saved
160 search in emacs):
161
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
165
166 You might or might not want as many exclusions.  Another interesting
167 search is:
168
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
173
174 See the [[status|https://nmbug.notmuchmail.org/status]] page for more
175 example searches.
176
177 ## Design notes
178
179 ### Disk format
180
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:
185
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
192
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).
195
196 ### Assumptions
197
198 - Currently the parser of nmbug (like that of notmuch restore) assumes
199   that there are no spaces in message-ids.
200
201 [archive]: https://nmbug.notmuchmail.org/archive/notmuch-list.tar.xz
202 [nmbug]: https://git.notmuchmail.org/git/notmuch/blob/HEAD:/devel/nmbug/nmbug