From 202c8b983924330b7a216299c5e48c2fa8ab024a Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Fri, 31 Mar 2017 18:33:06 +0100 Subject: [PATCH] git-debrebase: README tidy up --- README.git-debrebase | 196 ++++++++++--------------------------------- 1 file changed, 46 insertions(+), 150 deletions(-) diff --git a/README.git-debrebase b/README.git-debrebase index 35dcbf7c..6b92faf9 100644 --- a/README.git-debrebase +++ b/README.git-debrebase @@ -1,75 +1,48 @@ -From: Ian Jackson -To: Russ Allbery -Cc: debian-devel@lists.debian.org -Subject: Re: Feedback on 3.0 source format problems -Date: Wed, 4 Jan 2017 12:08:57 +0000 -Russ Allbery writes ("Re: Feedback on 3.0 source format problems"): -> Even if we never used tarballs, and instead our unit of operation was the -> upstream Git repository plus Debian branches, I would maintain a rebased -> branch of Debian changes to upstream -I think this is definitely the right thing for many packages. - -I don't think this depends on the interchange format representing the -changes as patches rather than commits. At a technical level, they -represent roughly the same information and it is possible to -interconvert. However: - - * There are many changes that patches cannot represent. - - * git (working with a rebasing branch) is a much more powerful tool - for editing a patch series than quilt or diff/patch or emacs - (working with a series of patches as files). Ie, patches are a - poor editing format. Consequently most people actually gateway to - git at the first opportunity, and out again for export. +My preferred answer is that it is a constantly rebasing branch topped +with a series of pseudomerges to make it fast-forwarding. - * Few people outside Debian work with quilt stacks any more. + ------/--A!----/--B3!--%--/--> interchange view + / / / with debian/ directory + % % % all upstream changes applied + / / / 3.0 (quilt) has debian/patches + / / 3* + / / / + 2* 2* 2 + / / / + 1 1 1 `breakwater' branch, merging baseline + / / / unmodified upstream code + ---p-----p--A----p--B--C--> plus debian/ (but no debian/patches) + / / / + --#-----#-------#-----> upstream -All of these things mean that patches are a really poor interchange -format. + Key: -The only difficulty is this one: + 1,2,3 commits touching upstream files only + A,B,C commits touching debian/ only + B3 mixed commit (eg made by an NMUer) + # upstream releases -> This is actually, in a way, *harder* if we were using pure Git, since if I -> have a rebased branch of Debian changes on top of upstream, and I need a -> place to integrate that with Debian packaging, what does that -> debian/master branch look like? I don't really want it to be a constantly -> rebased branch; I want it to be a conventional branch. But I want to keep -> merging the changes against upstream into it (but not maintain them on -> that branch, only maintain the Debian packaging files on that branch). + -p- special merge, takes contents of debian/ from the + / previous `breakwater' commit and rest from upstream -My preferred answer is that it is a constantly rebasing branch topped -with a series of pseudomerges to make it fast-forwarding. + -/- pseudomerge; contents are identical to + / parent lower on diagram. -git-dpm sort of does this. I have been experimenting with and -blundering towards another approach, which is closer to raw git. - -Something like this: - - ------/--A-----/---B3---/--> interchange view - / / / - / / 3 - / / / - 2 2 2 - / / / - 1 1 1 - / / / - ---p-----p--A----p---B---> `packaging-only' branch - / / / - --#-----#-------#-----> upstream + % dgit-generated commit of debian/patches. + `3.0 (quilt)' only; dropped by rebase tool. - Key: 1,2,3 commits touching upstream files - A,B commits touching debian/ only - B3 mixed commit (eg made by an NMUer) - # upstream releases + * Maintainer's HEAD was here while they were editing, + before they said they were done, at which point their + tools generated [% and] -/- commit[s] to convert to + the fast-forwarding interchange branch. (Maybe the + tooling is simply `dgit push'.) - -p- special merge, takes contents of debian/ - / from the previous `packaging only' - commit and rest from upstream + ! NMUer's HEAD was here when they said `dgit push'. + Rebase branch launderer turns each ! into an + equivalent *. - -/- pseudomerge; contents are identical to - / parent lower on diagram. Looking from the tip of the interchange view, it is I think always possible to classify these commits appropriately: pseudomerges are @@ -77,20 +50,19 @@ fairly obvious (if all three trees are identical, we descend to the parent with the most recent commit date), and the `p' special merge is the only non-pseudo merge and has a special form. -So it would be possible to write a `git-debian-rebase' tool which -would take (for example) B3, above, and be able to perform functions -like: +So it would be possible to write a `git-debrebase' tool which would +take (for example) B4, above, and be able to perform functions like: * Strip pseudomerges: Rewrite the current branch so it contains no - pseudomerges, turning ...B3 into ...p-A-1-2-B3. (This should make - a note, in your .git/ somewhere, of the latest pseudomerge to be - deleted.) + pseudomerges, turning ...B3 into ...p-A-1-2-B3. (This should + make a note, in your .git/ somewhere, of the latest pseudomerge to + be deleted.) * Cleanup branch: Reorganise the current branch so that the debian/ - changes come first, turning -p-A-1-2-B3 into ...p-A-B-1-2. + changes come first, turning -p-A-1-2-B3 into ...p-A-B-1-2-3. * New upstream rebase: Start rebasing onto a new upstream version, - turning ...#...p-A-B-1-2 into ...#'...p'-1-2. This would be a + turning ...#...p-A-B-1-2-3 into ...#'.A-B-p'-1-2. This would be a wrapper around git-rebase, which prepares p' and then tries to rebase 1 2 onto p'. So if you ask for an interactive rebase p' doesn't appear in your commit list. @@ -117,89 +89,13 @@ easy to reliably distinguish the two parents of a `p'. In the most exciting edge case, upstream might `git merge' a previous instance of our interchange view, but I think even then everything still works.) -Ian. - --- -Ian Jackson These opinions are my own. - -If I emailed you from an address @fyvzl.net or @evade.org.uk, that is -a private address which bypasses my fierce spamfilter. - -From: Ian Jackson -To: Sean Whitton -Cc: debian-devel@lists.debian.org -Subject: Re: Feedback on 3.0 source format problems -Date: Fri, 6 Jan 2017 15:29:38 +0000 - Sean Whitton writes ("Re: Feedback on 3.0 source format problems"): -> Could you explain in general terms the difference between the -> interchange and packaging-only branches - -See modified diagram below. Are the annotations I have added (and the -name change) any help ? - -> Does the packaging-only branch contain debian/ alone? +> Does the [breakwater] branch contain debian/ alone? No, it also contains a complete unmodified copy of the upstream code. (Except that if upstream had a debian/ directory, it is completely -replaced.) Perhaps this is the wrong name. Let's try -`merging-baseline' - -For `3.0 (quilt)' the merging-baseline branch contains roughly what -you would get if you untarred the origs and the debian.tar.gz, and -then deleted all the patches without applying them. - -Not shown on the diagram is the commit `add patch queue to -debian/patches', which would be needed for `3.0 (quilt)'. This is -because the diagram is in terms of a sane source format, not `3.0 -(quilt)'. For use with quilty sources, there would be such a commit -(probably dgit-generated) on top of the actual upstream change -commits: - - ------/--A!----/--B3!--%--/--> interchange view - / / / with debian/ directory - % % % all upstream changes applied - / / / 3.0 (quilt) has debian/patches - / 2* 2* - / / / - 2* 2 2 - / / / - 1 1 1 `merging-baseline' branch - / / / unmodified upstream code - ---p-----p--A----p--B--C--> plus debian/ (but no debian/patches) - / / / - --#-----#-------#-----> upstream - - Key: - - 1,2,3 commits touching upstream files only - A,B,C commits touching debian/ only - B3 mixed commit (eg made by an NMUer) - # upstream releases - - -p- special merge, takes contents of debian/ from the - / previous `merging-baseline' commit and rest from upstream - - -/- pseudomerge; contents are identical to - / parent lower on diagram. - - % dgit-generated commit of debian/patches. - `3.0 (quilt)' only; dropped by rebase tool. - - * Maintainer's HEAD was here while they were editing, - before they said they were done, at which point their - tools generated [% and] -/- commit[s] to convert to - the fast-forwarding interchange branch. (Maybe the - tooling is simply `dgit push'.) - - ! NMUer's HEAD was here when they said `dgit push'. - Rebase branch launderer turns each ! into an - equivalent *. - -Ian. - --- -Ian Jackson These opinions are my own. +replaced.) -If I emailed you from an address @fyvzl.net or @evade.org.uk, that is -a private address which bypasses my fierce spamfilter. +For `3.0 (quilt)' the breakwater branch contains roughly what you +would get if you untarred the origs and the debian.tar.gz, and then +deleted all the patches without applying them. -- 2.30.2