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