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 should 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 ### Bug tracking tag
 115
 116 So far we are just tagging certain messages as bug reports, meaning
 117 things that "everyone" agrees should be fixed.
 118
 119     notmuch::bug                is a bug report
 120     notmuch::fixed              indicates that the bug is fixed in the
 121                                 master branch
 122
 123 ### Optional tags
 124
 125 These patches are more comments and suggestions.
 126
 127     notmuch::doc                is a documentation patch
 128     notmuch::emacs              is a patch/bug for the emacs UI
 129     notmuch::feature            provides a new feature
 130     notmuch::fix                fixes a bug
 131     notmuch::portability        improves portability
 132     notmuch::review             is a review
 133     notmuch::test               provides a new test/or improves testing
 134     notmuch::$n                 this patch should be considered for
 135                                 release $n
 136
 137 ## Tracking the patch queue
 138
 139 I (David Bremner) use the following search (in my case as a saved
 140 search in emacs):
 141
 142     tag:notmuch::patch and not tag:notmuch::pushed and \
 143         not tag:notmuch::obsolete and not tag:notmuch::wip \
 144             and not tag:notmuch::moreinfo and not tag:notmuch::contrib
 145
 146 You might or might not want as many exclusions.  Another interesting
 147 search is:
 148
 149     tag:notmuch::reviewed and not tag:notmuch::pushed
 150
 151 ## Design notes
 152
 153 ### Disk format
 154
 155 The tags are stored in a bare-repo, which means they are not obviously
 156 visible. There is an `nmbug archive` command analogous to `git
 157 archive` Tags are represented as empty files in the tree; if you extra
 158 them, the tree looks something like:
 159
 160     tags/878waiwi0f.wl%25james@hackervisions.org/
 161     tags/878waiwi0f.wl%25james@hackervisions.org/emacs
 162     tags/878waiwi0f.wl%25james@hackervisions.org/patch
 163     tags/87aa8j7hqu.fsf@zancas.localnet/
 164     tags/87aa8j7hqu.fsf@zancas.localnet/patch
 165     tags/87aa8j7hqu.fsf@zancas.localnet/pushed
 166
 167 The `%25` represents hex code for a character that cannot be used directly
 168 (in this case %, only because it is needed as an escape).
 169
 170 ### Assumptions
 171
 172 - Currently the parser of nmbug (like that of notmuch restore) assumes
 173   that there are no spaces in message-ids.