DESIGN

   1 Patch removal:
   2
   3  - removed patch must be removed from the deps of its
   4    ex-children, and replaced with the deps of the removed
   5    patch
   6
   7  - removed patch wants not to be in list of patches "tb-list"
   8    et al any more
   9       branches in refs/topbloke-tips ?  yes
  10       deleted patches do something to the base ?  no
  11
  12  deleting empty patch: dependencies fine
  13  deleting nonempty patch: if any dependencies found, their
  14     updates break
  15
  16  purpose of deleting?
  17    - remove from views of active patches
  18    - prevent new commits
  19    - remove from dependencies of active patches
  20        only makes sense if no active patches depend on it.
  21
  22  undeleting
  23    - just unmark the patch as deleted
  24
  25
  26 Foreign branches:
  27  When merging from a foreign dependency, check that it
  28  does not have .topbloke metadata; LATER if it
  29  does, could produce a new commit which has .topbloke removed
  30  and merge from that
  31
  32 Patch naming:
  33  needs to be globally unique
  34  so put email address in it
  35 tg operations search for applicable patches
  36 safe charset for patch names
  37   . - / 0-9 a-z
  38 not permitted (git-check-ref-format(1))
  39  spc ~ ^ : ? * [ \
  40  @{ .lock.
  41  (apropos of shell)
  42
  43
  44 When pulling, which remotes get to update which patches ?
  45 Complicated question!
  46
  47 For now, have "blessed" remotes, which we always pull and update from.
  48 All these count as sources above.
  49
  50 Update operation restrictions available, which restrict use of various
  51 sources above ?  What about implications for correctness of merge
  52 algorithm ?
  53
  54
  55 Concept of a "stack" ?
  56 Unnecessary - instead, deal with leaf patches
  57 Operations like "go up the stack", goes towards leaf.  Hopefully unique.
  58 "Down" the stack, uses a "conventional" linearisation
  59 Stack reordering op ?  auto adjust deps
  60
  61
  62 When merging, we need to DTRT with our metadata.
  63 Do this by running write-tree/read-tree etc. ourselves ?
  64 For a source we're merging from, we make a version where the
  65 metadata we shouldn't be merging is removed ?
  66 Or something.
  67 Have discovered that specifying a custom merge driver for a file does
  68 not have any effect if the three-way-merge looks trivial based
  69 on looking at the file contents - at least, if you use git-merge.
  70
  71 Only thing which knows how to do all the gitattributes stuff and
  72 conflict markers and what have you is git-merge.  (git-merge-tree does
  73 too but the output format is unsuitable.)  "git-merge-index
  74 ... git-merge-one-file" does not honour the merge drivers and is,
  75 contrary to what the git docs seem to suggest but don't actually
  76 state, not actualy used by git-merge.
  77
  78 OK so here is a plan:
  79   Use git-merge --no-commit
  80   Perhaps on a HEAD, and/or against a tree, which have been massaged
  81    to make the metadata suitable as input.
  82   Filtering out the "merge was successful but we aren't committing"
  83   message.  Use a single pipe for stdout/stderr to get interleaving
  84   right; the message from git-merge is not i18n'd.
  85   Afterwards we:
  86   Check for merge success in the index and compare to exit status
  87   from git-merge (which is 1 if the merge failed).
  88   Adjust the metadata.
  89   Print appropriate big fat warnings if we have merge conflicts in our
  90   metadata.
  91   Commit, adjusting the parents of the new commit to the original
  92   parents if we made the merge with special massaged parents.
  93   We may still need to have custom merge drivers for metadata.
  94
  95
  96 Strategies for each metadata file merge:
  97
  98         in base/tip     same patch & branch     dep -> base     base -> tip
  99
 100  msg             T      textual merge           rm from src     not in src
 101  deps           B       list merge              rm from src     rm from src
 102  deleted         T      std existence merge     rm from src     not in src
 103  patch-         BT      must be same            rm from src     must be same
 104  topgit-        B       std exist/text merge    rm from src     rm from src
 105  [^+]*-         ??      textual merge           rm from src     rm from src
 106  +included      BT      list merge        rm from non-tb src    list merge
 107  +*-            ??      textual merge     rm from non-tb src    textual merge
 108  *[^-]          ??      die, aborting all ops, if found in any tb src or branch
 109
 110
 111
 112
 113
 114 Unwanted removal search subgraphs:
 115
 116   rm            relevant removal
 117   inc
 118
 119    rm           impossible to undo removal, arrgh, terminates search
 120 inc  inc..
 121 /  ???   \
 122
 123     rm
 124 inc..  rm..     merge of a removal, search down the rm path
 125 /  [inc]  \
 126
 127   inc           ??? call it an inclusion, terminate the search
 128   rm
 129
 130    inc          merge of an inclusion, terminates search
 131 inc..  rm..
 132 /  [rm]  \
 133
 134    inc          ??? call it an inclusion, terminate search
 135 rm..  rm..
 136 /  ???    \
 137
 138
 139   rm    inc       inc          rm       irrelevant
 140   rm    inc     inc inc..    rm rm..
 141
 142
 143
 144           OUR BASE              SOURCE                 OUR IT TIP
 145                 |                  |                       |
 146                 |                  |                       |
 147    ADD DEP WH/ inc                 rm                      |
 148     NEEDS IT   /|                  /\                      |
 149               / |                rm  \                     |
 150              /  | ______________'/    \                    |
 151           inc   |'              /      \                   |     IT tip
 152            /   inc     REMOVAL rm       \                  |    elsewhere
 153           /     |             /          \                 |   |   |
 154          /      |           inc           \                |   |   |
 155      some IT    |           /              |               |   |   |
 156                 |         inc              |               |   |   |
 157                /           |               |               |   |   |
 158               /          inc               |               |   |   |
 159              |           / |               |               |   |   |
 160             /           /  inc             |               |   |   |
 161            /           |   | `------------ | ----<-------- | -.|   |
 162           /           inc  inc             |               |   *2  |
 163           |            |`- | ------------- | ----<--------.|   |   |
 164           |            `---inc             |              1*  /    |
 165           |                |               |               | /     |
 166           |     RE-INCLUDE inc             rm REMOVAL      |'      |
 167         inc     \          |               |               |       |
 168           |      * REMOVAL rm              |               |       |
 169           |                |              /                |       |
 170           |`-------------- | ----------. /                 |       |
 171           |                |           inc ANC2            |       |
 172          inc               inc         /                   |       |
 173           |`.____________  |          /                    |       |
 174           |              `inc ANC1   /                     |       |
 175           |                |        /`--------<----------- | ---.  |
 176         without            inc     /                       |     \/
 177           |                |      /                        |     /
 178            \    RE-INCLUDE inc   /                         |    /
 179             \   \          |    /                          |   /
 180              \   * REMOVAL rm  /                           |  /
 181               \            |  /                            | /
 182                \           inc FIRST ADD DEP               |/
 183                 \          |  \                            *3
 184                  \         |   `------------<-------------.|
 185                   \        |                               |
 186                    \       without                         |
 187                     \_____ |                               |
 188                           `without                         |
 189                            |                               |
 190                                                           IT
 191
 192
 193   Merge 1* and 2*, diff against some relevant base branch commit
 194   or something, and apply to proposed. ???
 195
 196
 197 After we are done:
 198   source tip is included in our base
 199
 200 Each time:
 201   * pick common ancestor
 202   * compute whether merge from common anc would unwantedly remove
 203   * if so we arrange that the common anc is a "rm" but our branch
 204     actually contains IT