]> git.cworth.org Git - notmuch-wiki/blob - nmbug.mdwn
fixed "deleted" toggle order
[notmuch-wiki] / nmbug.mdwn
1 # Experimental Tag Sharing / Pseudo-Bug-Tracking for/with notmuch
2
3 ## Web View
4
5 There is a dump of (some views of) the nmbug [[status|http://nmbug.tethera.net/status]].
6
7 ## Getting started
8
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).
11
12    The nmbug script is available in `contrib/nmbug`.
13
14 2. The current tag repo can be obtained by:
15
16    `$ git clone --bare http://nmbug.tethera.net/git/nmbug-tags.git $HOME/.nmbug`
17
18    Check that your git is recent enough by entering:
19
20    `$ git --git-dir=$HOME/.nmbug fetch`
21
22    If you get failures then you need to update your git (as well).
23
24 ## Using nmbug, simple example
25
26     # get the latest version of the tags
27     $ nmbug pull
28
29     # do some tagging; see below for conventions
30     $ notmuch tag +notmuch::patch $id
31
32     # write the tag changes from the notmuch database
33     $ nmbug commit
34
35 ## Using nmbug, doing the same thing with more steps
36
37     # get the latest version of the tags
38     $ nmbug fetch
39
40     # Optionally inspect the fetched changes
41
42     $ nmbug status
43      a   tags/id1/patch
44      d   tags/id2/pushed
45
46     # merge the fetched tags into notmuch
47     $ nmbug merge
48
49     # observe status is clear now,
50     $ nmbug status
51
52     # make the tag changes
53     $ notmuch tag +notmuch::patch id
54
55     # double check your changes
56     $ nmbug status
57     A tags/id/patch
58
59     # write the tag changes
60     $ nmbug commit
61
62 ## Submitting tags
63
64 For the moment, we are using a central repo, hosted at:
65
66     nmbug@nmbug.tethera.net:nmbug-tags
67
68 To get push access, send your public key (ideally in a gpg signed
69 email) to David Bremner.  There is a convenience command:
70
71     $ nmbug push
72
73 But you will have to change your url with:
74
75     $ git --git-dir=$HOME/.nmbug remote set-url origin nmbug@nmbug.tethera.net:nmbug-tags
76
77 ## Tagging conventions
78
79 _Note that the tag database is probably catching up to these
80 conventions._
81
82 ### Main patch tracking tags
83
84 Initially any patch should be tagged:
85
86     notmuch::patch
87
88 Patches that are for discussion, rather than proposed for master should be tagged:
89
90     notmuch::wip                is "work in progress", posted for review or comment.
91
92 Most patches will be initially tagged:
93
94     notmuch::needs-review       needs some (more) review
95
96 unless they are tagged:
97
98     notmuch::trivial            looks harmless
99
100 Patches keep `notmuch::needs-review` until they either get enough
101 reviews, or one of the following resolutions is reached:
102
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
106                                 be applied
107
108 Sometimes the process stalls, and patches get tagged:
109
110     notmuch::moreinfo           waiting for feedback from patch proposer
111                                 or others
112     notmuch::stale              The patch no longer applies to master (or in 
113                                 rare cases, to release)                                                        
114 ### Bug tracking tag
115
116 So far we are just tagging certain messages as bug reports, meaning
117 things that "everyone" agrees should be fixed.
118
119     notmuch::bug                is a bug report
120     notmuch::fixed              indicates that the bug is fixed in the
121                                 master branch
122
123 ### Optional tags
124
125 These patches are more comments and suggestions.
126
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
135                                 release $n
136
137 ## Tracking the patch queue
138
139 I (David Bremner) use the following search (in my case as a saved
140 search in emacs):
141
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
145
146 You might or might not want as many exclusions.  Another interesting
147 search is:
148
149     tag:notmuch::reviewed and not tag:notmuch::pushed
150
151 ## Design notes
152
153 ### Disk format
154
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:
159
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
166
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).
169
170 ### Assumptions
171
172 - Currently the parser of nmbug (like that of notmuch restore) assumes
173   that there are no spaces in message-ids.