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.
  10
  11    The nmbug script is available in `contrib/nmbug`.
  12
  13 2. The current tag repo can be obtained by:
  14
  15    `$ git clone --bare http://nmbug.tethera.net/git/nmbug-tags.git $HOME/.nmbug`
  16
  17    Check that your git is recent enough by entering:
  18
  19    `$ git --git-dir=$HOME/.nmbug fetch`
  20
  21    If you get failures then you need to update your git (as well).
  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 git@pivot.cs.unb.ca:pub/nmbug
  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 should be tagged:
  88
  89     notmuch::wip                is "work in progress", posted for review or comment.
  90
  91 Most patches will be initially tagged:
  92
  93     notmuch::needs-review       needs some (more) review
  94
  95 unless they are tagged:
  96
  97     notmuch::trivial            looks harmless
  98
  99 Patches keep `notmuch::needs-review` until they either get enough
 100 reviews, or one of the following resolutions is reached:
 101
 102     notmuch::obsolete           replaced by some other patch
 103     notmuch::pushed             is pushed to master
 104     notmuch::wontfix            for whatever reason, this patch will not
 105                                 be applied
 106
 107 Sometimes the process stalls, and patches get tagged:
 108
 109     notmuch::moreinfo           waiting for feedback from patch proposer
 110                                 or others
 111
 112 ### Bug tracking tag
 113
 114 So far we are just tagging certain messages as bug reports, meaning
 115 things that "everyone" agrees should be fixed.
 116
 117     notmuch::bug                is a bug report
 118
 119 ### Optional tags
 120
 121 These patches are more comments and suggestions.
 122
 123     notmuch::emacs              is a patch/bug for the emacs UI
 124     notmuch::feature            provides a new feature
 125     notmuch::fix                fixes a bug
 126     notmuch::portability        improves portability
 127     notmuch::review             is a review
 128     notmuch::test               provides a new test/or improves testing
 129     notmuch::$n                 this patch should be considered for
 130                                 release $n
 131
 132 ## Tracking the patch queue
 133
 134 I (David Bremner) use the following search (in my case as a saved
 135 search in emacs):
 136
 137     tag:notmuch::patch and not tag:notmuch::pushed and \
 138         not tag:notmuch::obsolete and not tag:notmuch::wip \
 139             and not tag:notmuch::moreinfo and not tag:notmuch::contrib
 140
 141 You might or might not want as many exclusions.  Another interesting
 142 search is:
 143
 144     tag:notmuch::reviewed and not tag:notmuch::pushed
 145
 146 ## Design notes
 147
 148 ### Disk format
 149
 150 The tags are stored in a bare-repo, which means they are not obviously
 151 visible. There is an `nmbug archive` command analogous to `git
 152 archive` Tags are represented as empty files in the tree; if you extra
 153 them, the tree looks something like:
 154
 155     tags/878waiwi0f.wl%25james@hackervisions.org/
 156     tags/878waiwi0f.wl%25james@hackervisions.org/emacs
 157     tags/878waiwi0f.wl%25james@hackervisions.org/patch
 158     tags/87aa8j7hqu.fsf@zancas.localnet/
 159     tags/87aa8j7hqu.fsf@zancas.localnet/patch
 160     tags/87aa8j7hqu.fsf@zancas.localnet/pushed
 161
 162 The `%25` represents hex code for a character that cannot be used directly
 163 (in this case %, only because it is needed as an escape).
 164
 165 ### Assumptions
 166
 167 - Currently the parser of nmbug (like that of notmuch restore) assumes
 168   that there are no spaces in message-ids.