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 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
  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::reviewed and not tag:notmuch::pushed
 157
 158 See the [[status|http://nmbug.tethera.net/status]] page for more
 159 example searches.
 160
 161 ## Design notes
 162
 163 ### Disk format
 164
 165 The tags are stored in a bare-repo, which means they are not obviously
 166 visible. There is an `nmbug archive` command analogous to `git
 167 archive` Tags are represented as empty files in the tree; if you extra
 168 them, the tree looks something like:
 169
 170     tags/878waiwi0f.wl%25james@hackervisions.org/
 171     tags/878waiwi0f.wl%25james@hackervisions.org/emacs
 172     tags/878waiwi0f.wl%25james@hackervisions.org/patch
 173     tags/87aa8j7hqu.fsf@zancas.localnet/
 174     tags/87aa8j7hqu.fsf@zancas.localnet/patch
 175     tags/87aa8j7hqu.fsf@zancas.localnet/pushed
 176
 177 The `%25` represents hex code for a character that cannot be used directly
 178 (in this case %, only because it is needed as an escape).
 179
 180 ### Assumptions
 181
 182 - Currently the parser of nmbug (like that of notmuch restore) assumes
 183   that there are no spaces in message-ids.