git.cworth.org Git - notmuch-wiki/blob - 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|http://nmbug.tethera.net/status]].
   7
   8 ## Getting started
   9
  10 0. Make sure that the whole [notmuch&#64;notmuchmail.org mailing list
  11    archive][archive] is available in your email database.
  12
  13 1. Install and use nmbug from notmuch version **0.18** or newer and
  14    perl module `Pod::Usage` (packaged as `perl-doc` in debian).
  15
  16    The nmbug script is available in [devel/nmbug][nmbug].
  17
  18 2. Make sure your `git version` is **1.7.4** or newer.
  19
  20 3. Enter the following command to obtain the current tag repository:
  21
  22    `$ nmbug clone http://nmbug.tethera.net/git/nmbug-tags.git`
  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
  89 should also be tagged:
  90
  91     notmuch::wip                is "work in progress", posted for review or comment.
  92
  93 Most patches will be initially tagged:
  94
  95     notmuch::needs-review       needs some (more) review
  96
  97 unless they are tagged:
  98
  99     notmuch::trivial            looks harmless
 100
 101 Patches keep `notmuch::needs-review` until they either get enough
 102 reviews, or one of the following resolutions is reached:
 103
 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
 107                                 be applied
 108
 109 Sometimes the process stalls, and patches get tagged:
 110
 111     notmuch::moreinfo           waiting for feedback from patch proposer
 112                                 or others
 113     notmuch::stale              The patch no longer applies to master (or in
 114                                 rare cases, to release)
 115
 116 Note that these tags typically apply to whole series of patches; it
 117 doesn't usually make sense to apply patches later in the series before
 118 earlier ones. So a patch may be tagged `moreinfo` or `stale` only
 119 because a predecessor patch is.
 120
 121 ### Bug tracking tag
 122
 123 So far we are just tagging certain messages as bug reports, meaning
 124 things that "everyone" agrees should be fixed.
 125
 126     notmuch::bug                is a bug report
 127     notmuch::fixed              indicates that the bug is fixed in the
 128                                 master branch
 129
 130 ### Optional tags
 131
 132 These patches are more comments and suggestions.
 133
 134     notmuch::doc                is a documentation patch
 135     notmuch::emacs              is a patch/bug for the emacs UI
 136     notmuch::feature            provides a new feature
 137     notmuch::fix                fixes a bug
 138     notmuch::portability        improves portability
 139     notmuch::review             is a review
 140     notmuch::test               provides a new test/or improves testing
 141     notmuch::$n                 this patch should be considered for
 142                                 release $n
 143
 144 ## Tracking the patch queue
 145
 146 I (David Bremner) use the following search (in my case as a saved
 147 search in emacs):
 148
 149     tag:notmuch::patch and not tag:notmuch::pushed and \
 150         not tag:notmuch::obsolete and not tag:notmuch::wip \
 151             and not tag:notmuch::moreinfo and not tag:notmuch::contrib
 152
 153 You might or might not want as many exclusions.  Another interesting
 154 search is:
 155
 156     tag:notmuch::patch and not tag:notmuch::needs-review and not \
 157         tag:notmuch::pushed and not tag:notmuch::obsolete and not \
 158             tag:notmuch::wontfix and not tag:notmuch::moreinfo and not \
 159                 tag:notmuch::stale and not tag:notmuch::wip
 160
 161 See the [[status|http://nmbug.tethera.net/status]] page for more
 162 example searches.
 163
 164 ## Design notes
 165
 166 ### Disk format
 167
 168 The tags are stored in a bare-repo, which means they are not obviously
 169 visible. There is an `nmbug archive` command analogous to `git
 170 archive` Tags are represented as empty files in the tree; if you
 171 extract them, the tree looks something like:
 172
 173     tags/878waiwi0f.wl%25james@hackervisions.org/
 174     tags/878waiwi0f.wl%25james@hackervisions.org/emacs
 175     tags/878waiwi0f.wl%25james@hackervisions.org/patch
 176     tags/87aa8j7hqu.fsf@zancas.localnet/
 177     tags/87aa8j7hqu.fsf@zancas.localnet/patch
 178     tags/87aa8j7hqu.fsf@zancas.localnet/pushed
 179
 180 The `%25` represents hex code for a character that cannot be used directly
 181 (in this case %, only because it is needed as an escape).
 182
 183 ### Assumptions
 184
 185 - Currently the parser of nmbug (like that of notmuch restore) assumes
 186   that there are no spaces in message-ids.
 187
 188 [archive]: http://notmuchmail.org/archives/notmuch.mbox
 189 [nmbug]: http://git.notmuchmail.org/git/notmuch/blob/HEAD:/devel/nmbug/nmbug