git.cworth.org Git - notmuch-wiki/blob - nmbug.mdwn

   1 # Experimental Tag Sharing / Pseudo-Bug-Tracking for/with notmuch
   2
   3 ## Getting set up
   4
   5 1. Install and use notmuch version notmuch 0.9+63~gebd1adc or newer.
   6
   7    The nmbug script is available in contrib/nmbug
   8
   9 2. The current tag repo can be obtained by
  10
  11       git clone --bare git://pivot.cs.unb.ca/nmbug.git $HOME/.nmbug
  12
  13     Check that your git is recent enough by entering
  14
  15       git --git-dir=$HOME/.nmbug fetch
  16
  17     If you get failures then you need to update your git (as well).
  18
  19 ## Using nmbug, simple example
  20
  21     # get the latest version of the tags
  22     $ nmbug pull
  23
  24     # do some tagging; see below for conventions
  25
  26     $ notmuch tag +notmuch::patch $id
  27
  28     # write the tag changes from the notmuch database
  29     $ nmbug commit
  30
  31 ## Using nmbug, doing the same thing with more steps
  32
  33     # get the latest version of the tags
  34     $ nmbug fetch
  35
  36     # Optionally inspect the fetched changes
  37
  38     $ nmbug status
  39      a   tags/id1/patch
  40      d   tags/id2/pushed
  41
  42     # merge the fetched tags into notmuch
  43     $ nmbug merge
  44
  45     # observe status is clear now,
  46     $ nmbug status
  47
  48     # make the tag changes
  49     $ notmuch tag +notmuch::patch id
  50
  51     # double check your changes
  52     $ nmbug status
  53     A tags/id/patch
  54
  55     # write the tag changes
  56     $ nmbug commit
  57
  58 ## Submitting tags.
  59
  60    For the moment, we are using a central repo, hosted at
  61
  62         git@pivot.cs.unb.ca:pub/nmbug
  63
  64    To get push access, send your public key (ideally in a gpg signed
  65    email) to David Bremner.  There is a convenience command
  66
  67        nmbug push
  68
  69    But you will have to change your url with
  70
  71        git remote origin set-url git@pivot.cs.unb.ca:pub/nmbug
  72
  73 ## Tagging conventions
  74
  75     notmuch::bug                is a bug report
  76     notmuch::emacs              is a patch/bug for the emacs UI
  77     notmuch::feature            provides a new feature
  78     notmuch::fix                fixes a bug
  79     notmuch::moreinfo           waiting for feedback from patch proposer or others
  80     notmuch::obsolete           replaced by some other patch
  81     notmuch::patch
  82     notmuch::portability        improves portability
  83     notmuch::pushed             is pushed to master
  84     notmuch::review             is a review
  85     notmuch::reviewed           has been (well) reviewed
  86     notmuch::test               provides a new test/or improves testing
  87     notmuch::wip                is "work in progress", posted for review or comment.
  88
  89 ## Tracking the patch queue
  90
  91 I use the following search (in my case as a saved search in emacs).
  92
  93     tag:notmuch::patch and not tag:notmuch::pushed and \
  94         not tag:notmuch::obsolete and not tag:notmuch::wip \
  95             and not tag:notmuch::moreinfo
  96
  97 Another interesting search is
  98
  99     tag:notmuch::reviewed and not tag:notmuch::pushed
 100
 101
 102 ## Design notes
 103
 104 ### Disk format.
 105
 106 The tags are stored in a bare-repo, which means they are not obviously
 107 visible. There is an `nmbug archive` command analogous to `git
 108 archive` Tags are represented as empty files in the tree; if you extra
 109 them, the tree looks something like
 110
 111
 112     tags/878waiwi0f.wl%25james@hackervisions.org/
 113     tags/878waiwi0f.wl%25james@hackervisions.org/emacs
 114     tags/878waiwi0f.wl%25james@hackervisions.org/patch
 115     tags/87aa8j7hqu.fsf@zancas.localnet/
 116     tags/87aa8j7hqu.fsf@zancas.localnet/patch
 117     tags/87aa8j7hqu.fsf@zancas.localnet/pushed
 118
 119 The `%25` represents hex code for a character that cannot be used directly
 120 (in this case %, only because it is needed as an escape).
 121
 122 ### Assumptions
 123
 124 - Currently the parser of nmbug (like that of notmuch restore) assumes
 125   that there are no spaces in message-ids.
 126
 127
 128
 129