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