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