git.cworth.org Git - notmuch-wiki/blob - 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 **0.10** 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. Make sure your `git version` is **1.7.4** or newer.
  15
  16 3. Enter the following command to obtain the current tag repository:
  17
  18    `$ git clone --bare http://nmbug.tethera.net/git/nmbug-tags.git $HOME/.nmbug`
  19
  20 ## Using nmbug, simple example
  21
  22     # get the latest version of the tags
  23     $ nmbug pull
  24
  25     # do some tagging; see below for conventions
  26     $ notmuch tag +notmuch::patch $id
  27
  28     # write the tag changes from the notmuch database
  29     $ nmbug commit
  30
  31 ## Using nmbug, doing the same thing with more steps
  32
  33     # get the latest version of the tags
  34     $ nmbug fetch
  35
  36     # Optionally inspect the fetched changes
  37
  38     $ nmbug status
  39      a   tags/id1/patch
  40      d   tags/id2/pushed
  41
  42     # merge the fetched tags into notmuch
  43     $ nmbug merge
  44
  45     # observe status is clear now,
  46     $ nmbug status
  47
  48     # make the tag changes
  49     $ notmuch tag +notmuch::patch id
  50
  51     # double check your changes
  52     $ nmbug status
  53     A tags/id/patch
  54
  55     # write the tag changes
  56     $ nmbug commit
  57
  58 ## Submitting tags
  59
  60 For the moment, we are using a central repo, hosted at:
  61
  62     nmbug@nmbug.tethera.net:nmbug-tags
  63
  64 To get push access, send your public key (ideally in a gpg signed
  65 email) to David Bremner.  There is a convenience command:
  66
  67     $ nmbug push
  68
  69 But you will have to change your url with:
  70
  71     $ git --git-dir=$HOME/.nmbug remote set-url origin nmbug@nmbug.tethera.net:nmbug-tags
  72
  73 ## Tagging conventions
  74
  75 _Note that the tag database is probably catching up to these
  76 conventions._
  77
  78 ### Main patch tracking tags
  79
  80 Initially any patch should be tagged:
  81
  82     notmuch::patch
  83
  84 Patches that are for discussion, rather than proposed for master
  85 should also be tagged:
  86
  87     notmuch::wip                is "work in progress", posted for review or comment.
  88
  89 Most patches will be initially tagged:
  90
  91     notmuch::needs-review       needs some (more) review
  92
  93 unless they are tagged:
  94
  95     notmuch::trivial            looks harmless
  96
  97 Patches keep `notmuch::needs-review` until they either get enough
  98 reviews, or one of the following resolutions is reached:
  99
 100     notmuch::obsolete           replaced by some other patch
 101     notmuch::pushed             is pushed to master
 102     notmuch::wontfix            for whatever reason, this patch will not
 103                                 be applied
 104
 105 Sometimes the process stalls, and patches get tagged:
 106
 107     notmuch::moreinfo           waiting for feedback from patch proposer
 108                                 or others
 109     notmuch::stale              The patch no longer applies to master (or in
 110                                 rare cases, to release)
 111
 112 Note that these tags typically apply to whole series of patches; it
 113 doesn't usually make sense to apply patches later in the series before
 114 earlier ones. So a patch may be tagged `moreinfo` or `stale` only
 115 because a predecessor patch is.
 116
 117 ### Bug tracking tag
 118
 119 So far we are just tagging certain messages as bug reports, meaning
 120 things that "everyone" agrees should be fixed.
 121
 122     notmuch::bug                is a bug report
 123     notmuch::fixed              indicates that the bug is fixed in the
 124                                 master branch
 125
 126 ### Optional tags
 127
 128 These patches are more comments and suggestions.
 129
 130     notmuch::doc                is a documentation patch
 131     notmuch::emacs              is a patch/bug for the emacs UI
 132     notmuch::feature            provides a new feature
 133     notmuch::fix                fixes a bug
 134     notmuch::portability        improves portability
 135     notmuch::review             is a review
 136     notmuch::test               provides a new test/or improves testing
 137     notmuch::$n                 this patch should be considered for
 138                                 release $n
 139
 140 ## Tracking the patch queue
 141
 142 I (David Bremner) use the following search (in my case as a saved
 143 search in emacs):
 144
 145     tag:notmuch::patch and not tag:notmuch::pushed and \
 146         not tag:notmuch::obsolete and not tag:notmuch::wip \
 147             and not tag:notmuch::moreinfo and not tag:notmuch::contrib
 148
 149 You might or might not want as many exclusions.  Another interesting
 150 search is:
 151
 152     tag:notmuch::reviewed and not tag:notmuch::pushed
 153
 154 See the [[status|http://nmbug.tethera.net/status]] page for more
 155 example searches.
 156
 157 ## Design notes
 158
 159 ### Disk format
 160
 161 The tags are stored in a bare-repo, which means they are not obviously
 162 visible. There is an `nmbug archive` command analogous to `git
 163 archive` Tags are represented as empty files in the tree; if you
 164 extract them, the tree looks something like:
 165
 166     tags/878waiwi0f.wl%25james@hackervisions.org/
 167     tags/878waiwi0f.wl%25james@hackervisions.org/emacs
 168     tags/878waiwi0f.wl%25james@hackervisions.org/patch
 169     tags/87aa8j7hqu.fsf@zancas.localnet/
 170     tags/87aa8j7hqu.fsf@zancas.localnet/patch
 171     tags/87aa8j7hqu.fsf@zancas.localnet/pushed
 172
 173 The `%25` represents hex code for a character that cannot be used directly
 174 (in this case %, only because it is needed as an escape).
 175
 176 ### Assumptions
 177
 178 - Currently the parser of nmbug (like that of notmuch restore) assumes
 179   that there are no spaces in message-ids.