chiark / gitweb /
git-debrebase: NOTES: reword, record decisions about pm and ffq, tidy
[dgit.git] / NOTES.git-debrebase
1 TODO
2    reference docs
3       git-debrebase(5)   data model
4       git-debrebase(1)   command line
5    tutorial
6       dgit-maint-debrebase(7)
7       someone should set branch.<name>.mergeOptions to include --ff-only ?
8
9    clean up remains of NOTES and README
10
11    arrange for dgit to automatically stitch on push
12
13 ========================================
14
15 #  refs/ffq-prev/REF    relates to refs/REF
16
17 =======================================
18
19 special commit tags
20 overall format
21   [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
22
23 [git-debrebase: split mixed commit, debian part]
24 [git-debrebase: split mixed commit, upstream-part]
25 [git-debrebase: convert dgit import, debian changes]
26 [git-debrebase anchor: convert dgit import, upstream changes]
27
28 [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream]
29 [git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge]
30 [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog]
31
32 [git-debrebase convert-from-gbp: drop patches]
33 [git-debrebase anchor: declare upstream]
34 [git-debrebase pseudomerge: stitch]
35
36 [git-debrebase convert-to-gbp: commit patches]
37
38 m{^\[git-debrebase (?:\w*-)?upstream combine \.((?: $extra_orig_namepart_re)+)\]}
39
40 Every anchor commit must be a merge.  In principle, this is not
41 necessary.  After all, we are relying on the
42     [git-debrebase anchor: ...]
43 commit message annotation in "declare" anchor merges (which
44 do not have any upstream changes), to distinguish those anchor
45 merges from ordinary pseudomerges (which we might just try to strip).
46
47 However, the user is going to be doing git-rebase a lot.  We really
48 don't want them to rewrite an anchor commit.  git-rebase
49 trips up on merges, so that is a useful safety catch.
50
51 =======================================
52
53 workflow
54
55   git-debrebase blah [implies start]       strips pseudomerge(s)
56
57   commit / git-debrebase / etc.
58
59   dgit --damp-run push
60       hook: call git-debrebase prep-push   dgit push does not update remote
61       or something, must add patches at least
62
63   commit / git-debrebase / etc.            strips patches
64
65   dgit push
66       hook: call git-debrebase prep-push   dgit push DOES update remote
67
68   commit / git-debrebase / etc.            strips last pm, but arranges
69                                            that remade pm will incorporate it
70
71 ========================================
72
73 Theory for ffq-prev
74
75 When we strip a pm, we need to maybe record it (or something) as the
76 new start point.
77
78 When we do a thing
79
80     with no recorded ffq-prev
81
82         ffq-prev is our current tip
83
84         obviously it is safe to say we will overwrite this
85         we do check whether there are not-included changes in the remotes
86         because if the new ffq-prev is not ff from the remotes
87         the later pushes will fail
88
89         this model tends to keep ad-hoc commits made on our
90         tip branch before we did rebase start, in the
91         `interchange view' and also in the rebase stack.
92
93         also we can explicitly preserve with
94         git-debrebase stitch
95
96         It is always safe to rewind ffq-prev: all
97         that does is overwrite _less_ stuff.
98
99         in any case putative ffq-prev must be ff from remote.
100         Otherwise when we push it will not be ff, even though we have
101         made pseudomerge to overwrite ffq-prev.  So if we spot
102         this, report an error.  see above
103
104     with a recorded ffq-prev
105
106         we may need to advance ffq-prev, to allow us to generate
107         future pseudomerges that will be pushable
108
109         advancing ffq-prev is dangerous, since it might
110         effectively cancel the commits that will-ovewrite is advanced
111         over.
112
113         ??? advance it to merge-base( current remote, current tip )
114         if possible (see above), - ie to current remote, subject
115         to the condition that that is an ancestor of current tip
116
117         currently this is not implemented
118
119         better maybe to detect divergence ?  but it is rather late
120         by then!
121
122 We check we are ff from remotes before recording new ffq-prev
123
124   ---------- now follows much the same info in different words ----------
125
126 1. git-debrebase [-i etc.]
127
128      should:
129         check for ffq-prev
130         if is already a ffq-prev, fine, do no more
131         if not:
132
133         check our origin branch exists and we are ff from it
134         if not fail
135
136         check our other might-be-pushed to branches
137         check we are ff from them
138         if not fail
139
140         set ffq-prev to something which is ff from
141           all above branches
142
143         we use our tip, as discussed above
144         (optionally, can use some other commit which is ff
145          from all of the above, eg one of them)
146
147 N. git-debrebase [--noop-ok] record-ffq-prev
148
149      does what is described above
150
151 2. git-debrebase [--noop-ok] stitch
152
153     makes pseudomerge with ffq-prev
154     deletes ffq-prev
155
156     we will teach dgit to do
157        git-debrebase stitch
158
159 3. git-debrebase push
160
161     like git push only does stitch first
162     ??? command line parsing!
163
164 4. git-debrebase release
165
166     stiches, finalises changelog, signs tags, pushes everything
167     for the future, when there is some automatic builder
168
169 ffq-prev for each ref
170     refs/heads/FOO
171 is
172     refs/ffq-prev/FOO
173
174 ========================================
175
176 import from gbp
177
178 [ all this is done now:
179  inputs:
180    current HEAD (patches-unapplied),
181      this is going to be the base of the old breakwater
182    nominated upstream
183
184  checks:
185    HEAD:<upstream> = upstream:<upstream>
186    upstream..HEAD:<upstream> is empty (overrideable)
187    upstremm:debian is empty (overrideable)
188
189  procedure:
190    construct
191      run gbp pq import to generate pq branch
192      new breakwater is
193        old HEAD
194        commit to remove d/patches
195        anchor merge with upstream
196        "rebase" of pq branch, each commit with d/patches stripped
197 ]
198
199 what about dgit view branch ?
200 ideally, would make pseudomerge over dgit view
201 would need to check that dgit view is actually dgit view of
202   ond of our ancestors
203 failing that first push will need --overwrite
204
205 ========================================
206
207 how to handle divergence and merges (if not detected soon enough)
208
209 same problem
210  if merge, look at branches before merge
211  generate new combined branch
212  pseudomerge to overwrite merge
213
214 current avaiable strategies:
215
216  maybe launder foreign branch
217
218  if foreign branch is nmuish, can rebase it onto ours
219
220  could merge breakwaters (use analyse to find them)
221  merge breakwaters (assuming same upstream)
222  manually construct new patch queue by inspection of
223   the other two patch queues
224
225  instead of manually constructing patch queue, could use
226   gbp pq export and git merge the patch queues
227   (ie work with interdiffs)
228
229  if upstreams are different and one is ahead
230   simply treat that as "ours" and
231   do the work to import changes from the other
232
233  if upstreams have diverged, can
234   resolve somehow to make new upstream
235   do new-upstream on each branch separately
236   now reduced to previously "solved" problem
237
238  in future, auto patch queue merge algorithm
239   determine next patch to apply
240   there are three versions o..O, l..L, r..R
241   we have already constructed m (previous patch or merged breakwater)
242   try using vector calculus in the implied cube and compute
243    multiple ways to check consistency ?
244
245 ========================================
246
247 #    git-ffqrebase start [BASE]
248 #                # records previous HEAD so it can be overwritten
249 #                # records base for future git-ffqrebase
250 #    git-ffqrebase set-base BASE
251 #    git-ffqrebase <git-rebase options>
252 #    git-ffqrebase finish
253 #    git-ffqrebase status [BRANCH]