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