+TODO
+ tutorial
+ dgit-maint-debrebase(7)
+ someone should set branch.<name>.mergeOptions to include --ff-only ?
+
+ arrange for dgit to automatically stitch on push
+ dgit push usually needs to (re)make a pseudomerge. The "first"
+ git-debrebase stripped out the previous pseudomerge and could
+ remembeed the old HEAD. But the user has to manually stitch it.
+ To fix this, do we need a new push hook for dgit ?
+
+
+
workflow
git-debrebase blah [implies start] strips pseudomerge(s)
commit / git-debrebase / etc.
dgit --damp-run push
- hook: call git-debrebase prep-push adds new pm ? passes --overwrite ?
- dgit push does not update remote
+ hook: call git-debrebase prep-push dgit push does not update remote
+ or something, must add patches at least
- commit / git-debrebase / etc. strips pm(s) including last one
+ commit / git-debrebase / etc. strips patches
dgit push
- hook: call git-debrebase prep-push adds new pm ? passes --overwrite ?
- dgit push DOES update remote
+ hook: call git-debrebase prep-push dgit push DOES update remote
commit / git-debrebase / etc. strips last pm, but arranges
that remade pm will incorporate it
-Aha!
+
+# problems / outstanding questions:
+#
+# * dgit push with a `3.0 (quilt)' package means doing quilt
+# fixup. Usually this involves recommitting the whole patch
+# series, one at a time, with dpkg-source --commit. This is
+# terribly terribly slow. (Maybe this should be fixed in dgit.)
+#
+# * Workflow is currently clumsy. Lots of spurious runes to type.
+# There's not even a guide.
+#
+# * new-upstream-v0 has a terrible UI for multiple upstream pieces.
+# You end up with giant runic command lines. Does this matter /
+# One consequence of the lack of richness it can need -f in
+# fairly sensible situations.
+#
+# * There should be a good convention for the version number,
+# and unfinalised or not changelog, after new-upstream.
+#
+# * Handing of multi-orig dgit new-upstream .dsc imports is known to
+# be broken. They may be not recognised, improperly converted, or
+# their conversion may be unrecognised.
+#
+# * We need to develop a plausible model that works for derivatives,
+# who probably want to maintain their stack on top of Debian's.
+# downstream-rebase-launder-v0 may be a starting point?
+# maybe the hypothetical git-ffqrebase is part of it too.
+
+
+# undocumented usages:
+#
+# git-debrebase [<options>] downstream-rebase-launder-v0 # experimental
+
+
+========================================
+
+Theory for ffq-prev
+
+ refs/ffq-prev/REF relates to refs/REF
When we strip a pm, we need to maybe record it (or something) as the
new start point.
-We do this if the pm is contained within the output branch.
+When we do a thing
-Actually this is not special to PMs.
+ with no recorded ffq-prev
-We need to record a new to-be-overwritten commit
- merge-base( our branch tip, relevant remote )
+ ffq-prev is our current tip
-If this is not a descendant of the relevant remote, then we are going
-to have a problem when we push so issue a warning or fail.
+ obviously it is safe to say we will overwrite this
+ we do check whether there are not-included changes in the remotes
+ because if the new ffq-prev is not ff from the remotes
+ the later pushes will fail
+ this model tends to keep ad-hoc commits made on our
+ tip branch before we did rebase start, in the
+ `interchange view' and also in the rebase stack.
+ also we can explicitly preserve with
+ git-debrebase stitch
-How about
+ It is always safe to rewind ffq-prev: all
+ that does is overwrite _less_ stuff.
- git-debrebase start or git-debrebase [continue]
+ in any case putative ffq-prev must be ff from remote.
+ Otherwise when we push it will not be ff, even though we have
+ made pseudomerge to overwrite ffq-prev. So if we spot
+ this, report an error. see above
- with no recorded will-overwrite
+ with a recorded ffq-prev
- putative will-overwrite is
- one model:
- our current tip
- obviously it is safe to say we will overwrite this
- we do not need to worry about whether this will
- overwrite not-included changes in the remote
- because either the will-overwrite is not
- ff from the remote (in which case later failure,
- see below); or the will-overwrite _is_ ff
- from the remote ie our tip is later than the
- remote and includes all of its changes
+ we may need to advance ffq-prev, to allow us to generate
+ future pseudomerges that will be pushable
- this model tends to keep ad-hoc commits made on our
- tip branch before we did rebase start, in the
- `interchange view' and also in the rebase stack.
+ advancing ffq-prev is dangerous, since it might
+ effectively cancel the commits that will-ovewrite is advanced
+ over.
- other model:
- merge-base( current remote, current tip )
+ ??? advance it to merge-base( current remote, current tip )
+ if possible (see above), - ie to current remote, subject
+ to the condition that that is an ancestor of current tip
- it is safe to overwrite current tip, by the
- argument above
+ currently this is not implemented
- it is always safe to rewind will-overwrite: all
- that does is overwrite _less_ stuff
+ better maybe to detect divergence ? but it is rather late
+ by then!
- this is the earliest overwrite we can make that
- will be pushable to the remote
+We check we are ff from remotes before recording new ffq-prev
- in practical terms this can only be ff from the
- current remote if it is equal to the current remote;
- so what we are actually checking below is that our tip
- is ff from the remote. This ought to be true before
- the first of our rebases.
+ ---------- now follows much the same info in different words ----------
- this model tends to rewind and rebase ad-hoc commits
- made on our tip branch before we did rebase start,
- this is better
+Re git-debrebase [--noop-ok] stitch
- in any case putative will-overwrite must be ff from remote.
- Otherwise when we push it will not be ff, even though we have
- made pseudomerge to overwrite will-overwrite. So if we spot
- this, report an error.
+ we will teach dgit to do
+ git-debrebase stitch
+ or some such ?
- with a recorded will-overwrite
+following parts are not implemented and maybe aren't the
+best subcommand names etc.
- we may need to advance will-overwrite, to allow us to generate
- future pseudomerges that will be pushable
+3. git-debrebase push
- advancing will-overwrite is dangerous, since it might
- effectively cancel the commits that will-ovewrite is advanced
- over.
+ like git push only does stitch first
+ ??? command line parsing!
- we advance it to merge-base( current remote, current tip )
- if possible (see above), - ie to current remote, subject
- to the condition that that is an ancestor of current tip
+4. git-debrebase release
+
+ stiches, finalises changelog, signs tags, pushes everything
+ for the future, when there is some automatic builder
+
+========================================
+
+import from gbp
+
+what about dgit view branch ?
+ideally, would make pseudomerge over dgit view
+would need to check that dgit view is actually dgit view of
+ ond of our ancestors
+failing that first push will need --overwrite
+that is what is currently implemented
+
+========================================
+
+how to handle divergence and merges (if not detected soon enough)
+
+same problem
+ if merge, look at branches before merge
+ generate new combined branch
+ pseudomerge to overwrite merge
+
+current avaiable strategies:
+
+ maybe launder foreign branch
+
+ if foreign branch is nmuish, can rebase it onto ours
+
+ could merge breakwaters (use analyse to find them)
+ merge breakwaters (assuming same upstream)
+ manually construct new patch queue by inspection of
+ the other two patch queues
+
+ instead of manually constructing patch queue, could use
+ gbp pq export and git merge the patch queues
+ (ie work with interdiffs)
+
+ if upstreams are different and one is ahead
+ simply treat that as "ours" and
+ do the work to import changes from the other
+
+ if upstreams have diverged, can
+ resolve somehow to make new upstream
+ do new-upstream on each branch separately
+ now reduced to previously "solved" problem
-In each case we can strip pseudomerges freely, as needed. We do not
-want to record what pseudomerges we strip, because whether we need to
-keep them depends (only) on whether they have been pushed.
+ in future, auto patch queue merge algorithm
+ determine next patch to apply
+ there are three versions o..O, l..L, r..R
+ we have already constructed m (previous patch or merged breakwater)
+ try using vector calculus in the implied cube and compute
+ multiple ways to check consistency ?
-Is that actually true ? What if the user actually _wanted_ to keep
-the pseudomerge despite not having pushed it ?
+========================================
-In that case we need to advance will-overwrite past it. We could
-provide an explicit command to do this: it would advance
-will-overwrite to the current tip (see rules above, which show that
-this is OK). Or maybe to the last pseudomerge on the current tip,
-so that the overall result will be series of pseudomerges.
+For downstreams of Debian, sketch of git-ffqrebase
+# git-ffqrebase start [BASE]
+# # records previous HEAD so it can be overwritten
+# # records base for future git-ffqrebase
+# git-ffqrebase set-base BASE
+# git-ffqrebase <git-rebase options>
+# git-ffqrebase finish
+# git-ffqrebase status [BRANCH]