chiark / gitweb /
135cb6d342fd1635fcf647a7457a80b209916159
[topbloke.git] / 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