git-debrebase: docs updates

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

2 files changed, 76 insertions, 79 deletions

diff --git a/NOTES.git-debrebase b/NOTES.git-debrebase
index aa725b1..c268d75 100644
--- a/NOTES.git-debrebase
+++ b/NOTES.git-debrebase
@@ -1,3 +1,34 @@
+
+#
+#    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]
+#
+#  refs/ffqrebase-prev/BRANCH    BRANCH may be refs/...; if not it means
+#  refs/ffqrebase-base/BRANCH      refs/heads/BRANCH
+#                               zero, one, or both of these may exist
+#
+# git-debrebase without start, if already started, is willing
+# to strip pseudomerges provided that they overwrite exactly
+# the previous HEAD
+#  xxxx is this right ?  what matters is have we pushed
+#    I think in fact the right answer is:
+#       git-debrebase always strips out pseudomerges from its branch
+#       a pseudomerge is put in at the time we want to push
+#       at that time, we make a pseudomerge of the remote tracking
+#           branch (if raw git) or the dgit view (if dgit)
+#       for raw git git-ffqrebase, do want preciseley to record
+#           value of remote tracking branch or our branch, on start, so we
+#           overwrite only things we intend to
+#  the previous pseudomerge    check for tags and remote branches ?
+
+
+=========
+
 workflow
 
   git-debrebase blah [implies start]       strips pseudomerge(s)
diff --git a/git-debrebase b/git-debrebase
index 0e2e0b7..85cf331 100755
--- a/git-debrebase
+++ b/git-debrebase
@@ -3,7 +3,7 @@
 # Script helping make fast-forwarding histories while still rebasing
 # upstream deltas when working on Debian packaging
 #
-# Copyright (C)2017 Ian Jackson
+# Copyright (C)2017,2018 Ian Jackson
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -18,94 +18,60 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-#    git-debrebase new-upstreams-v0 \
-#             NEW-VERSION ORIG-COMMITISH
-#            [EXTRA-ORIG-NAME EXTRA-ORIG-COMMITISH ...]
-#            [<git-rebase options>]
 
 # usages:
-#    git-debrebase status
-#    git-debrebase start       # like ffqrebase start + debrebase launder
-#    git-debrebase new-upstream [stuff]  # see below
-#    git-debrebase <git-rebase options>  # does debrebase start if necessary
 #
-#    git-debrebase analyse
-#    git-debrebase launder     # prints breakwater tip
-#    git-debrebase create-new-upstream-breakwater [-f] <upstreaminfo>...
+#    git-debrebase [<options>] new-upstream-v0 \
+#             <new-version> <orig-commitish>
+#            [<extra-orig-name> <extra-orig-commitish> ...]
+#            [<git-rebase options>...]
 #
-# <upstreaminfo> is
-#    [,][<subdir>:][+]<commitid>[,...]
+#    git-debrebase [<options> --] [<git-rebase options...>]
+#    git-debrebase [<options>] analyse
+#    git-debrebase [<options>] launder         # prints breakwater tip etc.
+#    git-debrebase [<options>] downstream-rebase-launder-v0  # experimental
+
+# 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.)
+#
+#  * dgit push usually needs to (re)make a pseudomerge.  The "first"
+#    git-debrebase stripped out the previous pseudomerge and could
+#    have remembeed the HEAD.  But it's not quite clear what history
+#    ought to be preserved and what should be discarded.  For now
+#    the user will have to tell dgit --overwrite.
+#
+#    To fix this, do we need a new push hook for dgit ?
+#
+#  * Workflow is currently clumsy.  Lots of spurious runes to type.
+#    There's not even a guide.
+#
+#  * There are no tests.
 #
-# if initial comma is supplied, entries are not positional.  Unspecified
-# <subdir> means root (and there may be only one).
-# xxx want auto branch names
-# xxx too complicated
-# how about for now
-#    [+]<commit> [<subdir/> [+]<commit>...]
-# ?  plus options
-#     --new-upstream-different-subtrees
+#  * new-upstream-v0 has a terrible UI.  You end up with giant
+#    runic command lines.
 #
-#  automatic case
-#       git-debrebase new-upstream
-#             - previous breakwater merge must be gdr-generated
-#             - orig set is the same as before
-#             - implicitly uses upstream branches according to orig set
-#             - not all upstream branches need be updated
-#             - insists on fast-forward of each branch, unless
-#                  --force (or --force=<subdir>[/])
-#  branch set adjustments
-#       git-debrebase new-upstream --add <subdir>/
-#       git-debrebase new-upstream --rm <subdir>/
-#       git-debrebase new-upstream / [<subdir>/ ...]
-#             - orig set is adjusted
-#             - otherwise like auto (--add is not checked for ffness, obv)
-#             - multiple --add and --rm may be specified
-#             - --add makes new upstream the last contributor
-#  explicit
-#       git-debrebase / [<rootcommitid>] [<subdir>/ [<commitid>] ...]
-#             - orig set is precisely as specified now
-#             - previous breakwater merge is irrelevant
-#             - no fast forward checks
-#  for now only explicit with commitids
-
-#         implicitly uses `upstream'
-#                                     # (or multiple other branches)
-#       git-debrebase new-upstream \
-#             [<subdir>/]=<commitid>
-
-#    UPSTREAM[,[[SUBDIR:]SUBUPSTREAM]
-#    default for SUBDIR: is from previous upstream merge[xxx terminology]
-#    
+#    One consequence of the lack of richness it can need --force in
+#    fairly sensible situations and there is no way to tell it what
+#    you are really trying to do, other than just --force.  There
+#    should be an interface with some default branch names.
 #
-#xxx
-# when starting must record original start (for ff)
-# and new rebase basis
+#  * There should be a standard convention for the version number,
+#    and unfinalised or not changelog, after new-upstream.
 #
-#    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]
+#  * 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.
 #
-#  refs/ffqrebase-prev/BRANCH    BRANCH may be refs/...; if not it means
-#  refs/ffqrebase-base/BRANCH      refs/heads/BRANCH
-#                               zero, one, or both of these may exist
+#  * Docs need writing and updating.  Even README.git-debrebase
+#    describes a design but may not reflect the implementation.
 #
-# git-debrebase without start, if already started, is willing
-# to strip pseudomerges provided that they overwrite exactly
-# the previous HEAD
-#  xxxx is this right ?  what matters is have we pushed
-#    I think in fact the right answer is:
-#       git-debrebase always strips out pseudomerges from its branch
-#       a pseudomerge is put in at the time we want to push
-#       at that time, we make a pseudomerge of the remote tracking
-#           branch (if raw git) or the dgit view (if dgit)
-#       for raw git git-ffqrebase, do want preciseley to record
-#           value of remote tracking branch or our branch, on start, so we
-#           overwrite only things we intend to
-#  the previous pseudomerge    check for tags and remote branches ?
+#  * 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?
 
 use strict;