From 7a0e4d6676962e090eeb0038462db3754092b310 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sat, 17 Feb 2018 15:47:33 -0700 Subject: dgit-maint-debrebase(7): first draft Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 534 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 534 insertions(+) create mode 100644 dgit-maint-debrebase.7.pod diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod new file mode 100644 index 0000000..0b4e756 --- /dev/null +++ b/dgit-maint-debrebase.7.pod @@ -0,0 +1,534 @@ +=head1 NAME + +dgit - tutorial for package maintainers, using a workflow centered around git-debrebase(1) + +=head1 INTRODUCTION + +This document describes elements of a workflow for maintaining a +non-native Debian package using B. We maintain the Debian delta +as a series of git commits on our master branch. We use +git-debrebase(1) to shuffle our branch such that this series of git +commits appears at the end of the branch. This does not involve +rewriting any public git history. + +Some advantages of this workflow: + +=over 4 + +=item + +Manipulate the patch queue using the full power of git-rebase(1), +instead of relying on quilt(1), and without having to switch away to +another branch, as with gbp-pq(1). + +=item + +Avoid the git tree being dirtied by the application or unapplication +of patches, as they are always applied. + +=item + +Benefit from dgit's safety catches. In particular, ensure that your +upload always matches exactly your git HEAD. + +=item + +Provide your full git history in a standard format on B, +where it can benefit downstream dgit users, such as people using dgit +to do an NMU (see dgit-nmu-simple(7) and dgit-user(7)). + +=back + +This workflow is appropriate for packages where the Debian delta +contains multiple pieces which interact, or which you don't expect to +be able to upstream soon. For packages with simple and/or short-lived +Debian deltas, use of git-debrebase(1) might introduce unneeded +complexity. For such packages, consider the workflow described in +dgit-maint-merge(7). + +=head1 INITIAL DEBIANISATION + +=head2 When upstream tags releases in git + +This section explains how to start using this workflow with a new +package. It should be skipped when converting an existing package to +this workflow. + +Suppose that the latest stable upstream release is 1.2.2, and this has +been tagged '1.2.2' by upstream. + +=over 4 + + % git clone -oupstream https://some.upstream/foo.git + % cd foo + % git verify-tag 1.2.2 + % git reset --hard 1.2.2 + % git branch --unset-upstream + +=back + +The final command detaches your master branch from the upstream +remote, so that git doesn't try to push anything there, or merge +unreleased upstream commits. To maintain a copy of your packaging +branch on B in addition to B, you can do +something like this: + +=over 4 + + % git remote add -f origin salsa.debian.org:Debian/foo.git + % git push --follow-tags -u origin master + +=back + +Now go ahead and Debianise your package. Just make commits on the +master branch, adding things in the I directory. If you need +to patch the upstream source, see "EDITING THE PATCH QUEUE", below. +Note that there is no need to maintain a separate 'upstream' branch, +unless you also happen to be involved in upstream development. We +work with upstream tags rather than any branches, except when +forwarding patches (see FORWARDING PATCHES UPSTREAM, below). + +Finally, you need an orig tarball: + +=over 4 + + % git deborig + +=back + +See git-deborig(1) if this fails. + +This tarball is ephemeral and easily regenerated, so we don't commit +it anywhere (e.g. with tools like pristine-tar(1)). + +=head3 Verifying upstream's tarball releases + +=over 4 + +It can be a good idea to compare upstream's released tarballs with the +release tags, at least for the first upload of the package. If they +are different, you might need to add some additional steps to your +I, such as running autotools. + +A convenient way to perform this check is to import the tarball as +described in the following section, using a different value for +'upstream-tag', and then use git-diff(1) to compare the imported +tarball to the release tag. If they are the same, you can use +upstream's tarball instead of running git-deborig(1). + +=back + +=head2 When upstream releases only tarballs + +We need a virtual upstream branch with virtual release tags. +gbp-import-orig(1) can manage this for us. To begin + +=over 4 + + % mkdir foo + % cd foo + % git init + +=back + +Now create I: + +=over 4 + + [DEFAULT] + upstream-branch = upstream + debian-branch = master + upstream-tag = %(version)s + + sign-tags = True + pristine-tar = False + pristine-tar-commit = False + + [import-orig] + merge-mode = merge + +=back + +gbp-import-orig(1) requires a pre-existing upstream branch: + +=over 4 + + % git add debian/gbp.conf && git commit -m "create gbp.conf" + % git checkout --orphan upstream + % git rm -rf . + % git commit --allow-empty -m "initial, empty branch for upstream source" + % git checkout -f master + +=back + +Then we can import the upstream version: + +=over 4 + + % gbp import-orig --merge-mode=replace ../foo_1.2.2.orig.tar.xz + +=back + +Our upstream branch cannot be pushed to B, but since we +will need it whenever we import a new upstream version, we must push +it somewhere. The usual choice is B: + +=over 4 + + % git remote add -f origin salsa.debian.org:Debian/foo.git + % git push --follow-tags -u origin master upstream + +=back + +You are now ready to proceed as above, making commits to the +I directory. + +=head1 CONVERTING AN EXISTING PACKAGE + +This section explains how to convert an existing Debian package to +this workflow. It should be skipped when debianising a new package. + +=head2 No existing git history + +=over 4 + + % dgit clone foo + % cd foo + % git remote add -f upstream https://some.upstream/foo.git + +=back + +=head2 Existing git history using another workflow + +First, if you don't already have the git history locally, clone it, +and obtain the corresponding orig.tar from the archive: + +=over 4 + + % git clone salsa.debian.org:Debian/foo + % cd foo + % origtargz + +=back + +If your tree is patches-unapplied, you will need to make a commit +corresponding to each of the quilt patches. gbp-pq(1) can do this for +us: + +=over 4 + + % gbp pq import + % gbp pq switch + % git merge --ff-only patch-queue/master + % gbp pq drop + +=back + +Then make new upstream tags available: + +=over 4 + + % git remote add -f upstream https://some.upstream/foo.git + +=back + +=for dgit-test dpkg-source-ignores begin + +Now you simply need to ensure that your git HEAD is dgit-compatible, +i.e., it is exactly what you would get if you ran +B +and then unpacked the resultant source package. + +=for dgit-test dpkg-source-ignores end + +To achieve this, you might need to delete +I. One way to have dgit check your +progress is to run B. + +The first dgit push will require I<--overwrite>. If this is the first +ever dgit push of the package, consider passing +I<--deliberately-not-fast-forward> instead of I<--overwrite>. This +avoids introducing a new origin commit into your git history. (This +origin commit would represent the most recent non-dgit upload of the +package, but this should already be represented in your git history.) + +=head1 IMPORTING NEW UPSTREAM RELEASES + +=head2 Obtaining the release + +=head3 When upstream tags releases in git + +=over 4 + + % git remote update + +=back + +=head3 When upstream releases only tarballs + +You will need the I from "When upstream releases only +tarballs", above. You will also need your upstream branch. Above, we +pushed this to B. You will need to clone or fetch +from there, instead of relying on B/B alone. + +Then, either + +=over 4 + + % gbp import-orig --no-merge ../foo_1.2.3.orig.tar.xz + +=back + +or if you have a working watch file + +=over 4 + + % gbp import-orig --no-merge --uscan + +=back + +=head2 Importing the release + +=over 4 + + % git debrebase new-upstream-v0 1.2.3 + % dch -v1.2.3-1 New upstream release. + % git add debian/changelog && git commit -m changelog + +=back + +You can now review the merge of the new upstream release: + +=over 4 + + git diff debian/1.2.2-1..HEAD -- . ':!debian' + +=back + +Pass I<--stat> just to see the list of changed files, which is useful +to determine whether there are any new or deleted files to may need +accounting for in your copyright file. + +If you obtained a tarball from upstream, you are ready to try a build. +If you merged a git tag from upstream, you will first need to generate +a tarball: + +=over 4 + + % git deborig + +=back + +=head1 EDITING THE PATCH QUEUE + +=head2 Adding new patches + +Adding new patches is straightforward: just make commits touching only +files outside of the I directory. You can also use tools +like git-revert(1), git-am(1) and git-cherrypick(1). + +=head2 Editing patches: starting a debrebase + +git-debrebase(1) is a wrapper around git-rebase(1) which allows us to +edit, re-order and delete patches. Run + +=over 4 + + % git debrebase + +=back + +to start an interactive rebase. You can edit, re-order and delete +commits just as you would during B. Alternatively, you +can perform a non-interactive rebase like this: + +=over 4 + + % git debrebase -- [git-rebase options...] + +=back + +For example, + +=over 4 + + % git debrebase -- --autosquash + +=back + +A third alternative is to have git-debrebase(1) shuffle all the Debian +changes to the end of your branch, and then manipulate them yourself +using git-rebase(1). For example, + +=over 4 + + % git debrebase launder + % git rebase -i HEAD^5 # there are 4 Debian patches + +=back + +=head2 Editing patches: finishing a debrebase + +After completing the git rebase, your branch will not be a +fast-forward of the git HEAD you had before the rebase. This means +that we cannot push the branch anywhere. If you are ready to upload, +B or B will take care of fixing this up +for you. + +If you are not yet ready to upload, and want to push your branch to a +git remote such as B, + +=over 4 + + % git debrebase stitch + +=back + +Note that each time you stitch a debrebase you introduce a pseudomerge +into your git history, which may make it harder to read. Try to do +all of the editing of the patch queue that you think will be needed +for this upload in a single debrebase, so that there is a single +debrebase stitch. + +A strategy is to debrebase only right before you upload. Before that +point, instead of editing the existing patch series, you append fixup +commits (and reversions of commits) that alter the upstream source to +the required state. You can freely push and pull from +B during this. Just before uploading, you debrebase +to tidy everything up. + +=head1 BUILDING AND UPLOADING + +Use B, B, B and B as detailed in dgit(1). If any command fails, dgit will +provide a carefully-worded error message explaining what you should +do. If it's not clear, file a bug against dgit. Remember to pass +I<--new> for the first upload. + +After dgit pushing, be sure to git push to B, if +you're using that. + +As an alternative to B and friends, you can use a tool +like gitpkg(1). This works because like dgit, gitpkg(1) enforces that +HEAD has exactly the contents of the source package. gitpkg(1) is +highly configurable, and one dgit user reports using it to produce and +test multiple source packages, from different branches corresponding +to each of the current Debian suites. + +If you want to skip dgit's checks while iterating on a problem with +the package build (for example, you don't want to commit your changes +to git), you can just run dpkg-buildpackage(1) or debuild(1) instead. + +=head2 Laundering the patch queue before uploading + +Just before you B or B, you might want to +have git-debrebase(1) shuffle your branch such that the Debian patch +queue appears at the end: + +=over 4 + + % git debrebase launder + % dgit push-source + +=back + +Note that this will introduce a new pseudomerge. + +=head1 HANDLING DFSG-NON-FREE MATERIAL + +=head2 When upstream tags releases in git + +We create a DFSG-clean tag to import to master: + +=over 4 + + % git checkout -b pre-dfsg 1.2.3 + % git rm evil.bin + % git commit -m "upstream version 1.2.3 DFSG-cleaned" + % git tag -s 1.2.3+dfsg + % git checkout master + % git branch -D pre-dfsg + +=back + +Before invoking B, you should first +determine whether it would be legally dangerous for the non-free +material to be publicly accessible in the git history on +B. + +If it would be dangerous, there is a big problem; +in this case please consult your archive administrators +(for Debian this is the dgit administrator dgit-owner@debian.org +and the ftpmasters ftpmaster@ftp-master.debian.org). + +=head2 When upstream releases only tarballs + +The easiest way to handle this is to add a B field to +I, and a B setting in +I. See uscan(1). Alternatively, see the I<--filter> +option detailed in gbp-import-orig(1). + +=head1 FORWARDING PATCHES UPSTREAM + +The basic steps are: + +=over 4 + +=item 1. + +Create a new branch based off upstream's master branch. + +=item 2. + +git-cherry-pick(1) commits from your master branch onto your new +branch. + +=item 3. + +Push the branch somewhere and ask upstream to merge it, or use +git-format-patch(1) or git-request-pull(1). + +=back + +For example (and it is only an example): + +=over 4 + + % # fork foo.git on GitHub + % git remote add -f fork git@github.com:spwhitton/foo.git + % git checkout -b fix-error upstream/master + % git config branch.fix-error.pushRemote fork + % git cherry-pick master^2 + % git push + % # submit pull request on GitHub + +=back + +Note that when you merge an upstream release containing your forwarded +patches, a debrebase will transparently handle "dropping" the patches +that have been forwarded, "retaining" the ones that haven't. + +=head1 INCORPORATING NMUS + +=over 4 + + % dgit pull + +=back + +If the NMUer added new commits modifying the upstream source, you will +probably want to debrebase before your next upload to tidy those up. + +For example, the NMUer might have used git-revert(1) to unapply one of +your patches. A debrebase will strip both the patch and the reversion +from the patch series. + +=head1 SEE ALSO + +dgit(1), dgit(7) + +=head1 AUTHOR + +This tutorial was written and is maintained by Sean Whitton +. It contains contributions from other dgit +contributors too - see the dgit copyright file. -- cgit v1.2.3 From 28047ddbdfd69b3599d6b73aa054e3432ac2952a Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Tue, 3 Apr 2018 10:16:38 -0700 Subject: dgit-maint-debrebase(7): begin incorporating feedback Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 107 ++++++++++++++++----------------------------- 1 file changed, 38 insertions(+), 69 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 0b4e756..3c454e0 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -8,8 +8,8 @@ This document describes elements of a workflow for maintaining a non-native Debian package using B. We maintain the Debian delta as a series of git commits on our master branch. We use git-debrebase(1) to shuffle our branch such that this series of git -commits appears at the end of the branch. This does not involve -rewriting any public git history. +commits appears at the end of the branch. All the public git history +is fast-forwarding, i.e., we do not rewrite and force-push. Some advantages of this workflow: @@ -18,8 +18,9 @@ Some advantages of this workflow: =item Manipulate the patch queue using the full power of git-rebase(1), -instead of relying on quilt(1), and without having to switch away to -another branch, as with gbp-pq(1). +instead of relying on quilt(1), and without having to switch back and +forth between patches-applied and patches-unapplied branches when +committing changes and trying to build, as with gbp-pq(1). =item @@ -37,23 +38,28 @@ Provide your full git history in a standard format on B, where it can benefit downstream dgit users, such as people using dgit to do an NMU (see dgit-nmu-simple(7) and dgit-user(7)). +=item + +Minimise the amount you need to know about 3.0 (quilt) in order to +maintain Debian source packages which use that format. + =back This workflow is appropriate for packages where the Debian delta contains multiple pieces which interact, or which you don't expect to be able to upstream soon. For packages with simple and/or short-lived Debian deltas, use of git-debrebase(1) might introduce unneeded -complexity. For such packages, consider the workflow described in -dgit-maint-merge(7). +complexity (for examples, see "BEHAVIOUR TO AVOID" below). For such +packages, consider the workflow described in dgit-maint-merge(7). =head1 INITIAL DEBIANISATION -=head2 When upstream tags releases in git - This section explains how to start using this workflow with a new package. It should be skipped when converting an existing package to this workflow. +=head2 When upstream tags releases in git + Suppose that the latest stable upstream release is 1.2.2, and this has been tagged '1.2.2' by upstream. @@ -212,8 +218,15 @@ and obtain the corresponding orig.tar from the archive: =back If your tree is patches-unapplied, you will need to make a commit -corresponding to each of the quilt patches. gbp-pq(1) can do this for -us: +corresponding to each of the quilt patches. You can use + +=over 4 + + git debrebase convert-from-gbp + +=back + +or manually with gbp-pq(1): =over 4 @@ -348,14 +361,6 @@ can perform a non-interactive rebase like this: =back -For example, - -=over 4 - - % git debrebase -- --autosquash - -=back - A third alternative is to have git-debrebase(1) shuffle all the Debian changes to the end of your branch, and then manipulate them yourself using git-rebase(1). For example, @@ -363,10 +368,13 @@ using git-rebase(1). For example, =over 4 % git debrebase launder - % git rebase -i HEAD^5 # there are 4 Debian patches + % git rebase -i HEAD~5 # there are 4 Debian patches =back +If you take this approach, you should be very careful not to start the +rebase earlier than the beginning of the patch queue. + =head2 Editing patches: finishing a debrebase After completing the git rebase, your branch will not be a @@ -380,6 +388,7 @@ git remote such as B, =over 4 + % git debrebase launder % git debrebase stitch =back @@ -436,6 +445,16 @@ Note that this will introduce a new pseudomerge. =head1 HANDLING DFSG-NON-FREE MATERIAL +This covers only DFSG-non-free material. Material which is legally +dangerous (for example, files which are actually illegal) cannot be +handled this way. + +If you encounter possibly-legally-dangerous material in the upstream +source code you should seek advice. It is often best not to make a +fuss on a public mailing list (at least, not at first). Instead, +email your archive administrators. For Debian that is + To: dgit-owner@debian.org, ftpmaster@ftp-master.debian.org + =head2 When upstream tags releases in git We create a DFSG-clean tag to import to master: @@ -451,16 +470,6 @@ We create a DFSG-clean tag to import to master: =back -Before invoking B, you should first -determine whether it would be legally dangerous for the non-free -material to be publicly accessible in the git history on -B. - -If it would be dangerous, there is a big problem; -in this case please consult your archive administrators -(for Debian this is the dgit administrator dgit-owner@debian.org -and the ftpmasters ftpmaster@ftp-master.debian.org). - =head2 When upstream releases only tarballs The easiest way to handle this is to add a B field to @@ -468,46 +477,6 @@ I, and a B setting in I. See uscan(1). Alternatively, see the I<--filter> option detailed in gbp-import-orig(1). -=head1 FORWARDING PATCHES UPSTREAM - -The basic steps are: - -=over 4 - -=item 1. - -Create a new branch based off upstream's master branch. - -=item 2. - -git-cherry-pick(1) commits from your master branch onto your new -branch. - -=item 3. - -Push the branch somewhere and ask upstream to merge it, or use -git-format-patch(1) or git-request-pull(1). - -=back - -For example (and it is only an example): - -=over 4 - - % # fork foo.git on GitHub - % git remote add -f fork git@github.com:spwhitton/foo.git - % git checkout -b fix-error upstream/master - % git config branch.fix-error.pushRemote fork - % git cherry-pick master^2 - % git push - % # submit pull request on GitHub - -=back - -Note that when you merge an upstream release containing your forwarded -patches, a debrebase will transparently handle "dropping" the patches -that have been forwarded, "retaining" the ones that haven't. - =head1 INCORPORATING NMUS =over 4 -- cgit v1.2.3 From 4f6a9138ee88608bdf7849d609248a912f7d92b1 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Tue, 3 Apr 2018 10:24:33 -0700 Subject: dgit-maint-debrebase(7): add another advantage Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 3c454e0..63b9641 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -24,6 +24,12 @@ committing changes and trying to build, as with gbp-pq(1). =item +If you are using 3.0 (quilt), provide your delta queue as a properly +separated series of quilt patches in the source package that you +upload to the archive (unlike with dgit-maint-merge(7)). + +=item + Avoid the git tree being dirtied by the application or unapplication of patches, as they are always applied. -- cgit v1.2.3 From b18825ae3c8a2df5f40cebf0691e9efcd11f4ce9 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Tue, 3 Apr 2018 10:28:21 -0700 Subject: dgit-maint-debrebase(7): patch queue -> delta queue For consistency with git-debrebase(5). Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 63b9641..f46944f 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -17,7 +17,7 @@ Some advantages of this workflow: =item -Manipulate the patch queue using the full power of git-rebase(1), +Manipulate the delta queue using the full power of git-rebase(1), instead of relying on quilt(1), and without having to switch back and forth between patches-applied and patches-unapplied branches when committing changes and trying to build, as with gbp-pq(1). @@ -94,11 +94,11 @@ something like this: Now go ahead and Debianise your package. Just make commits on the master branch, adding things in the I directory. If you need -to patch the upstream source, see "EDITING THE PATCH QUEUE", below. +to patch the upstream source, see "EDITING THE DELTA QUEUE", below. Note that there is no need to maintain a separate 'upstream' branch, unless you also happen to be involved in upstream development. We -work with upstream tags rather than any branches, except when -forwarding patches (see FORWARDING PATCHES UPSTREAM, below). +work with upstream tags rather than any branches, except temporary +branches used to prepare patches for forwarding upstream, for example. Finally, you need an orig tarball: @@ -338,7 +338,7 @@ a tarball: =back -=head1 EDITING THE PATCH QUEUE +=head1 EDITING THE DELTA QUEUE =head2 Adding new patches @@ -379,7 +379,7 @@ using git-rebase(1). For example, =back If you take this approach, you should be very careful not to start the -rebase earlier than the beginning of the patch queue. +rebase earlier than the beginning of the delta queue. =head2 Editing patches: finishing a debrebase @@ -401,12 +401,12 @@ git remote such as B, Note that each time you stitch a debrebase you introduce a pseudomerge into your git history, which may make it harder to read. Try to do -all of the editing of the patch queue that you think will be needed +all of the editing of the delta queue that you think will be needed for this upload in a single debrebase, so that there is a single debrebase stitch. A strategy is to debrebase only right before you upload. Before that -point, instead of editing the existing patch series, you append fixup +point, instead of editing the existing delta queue, you append fixup commits (and reversions of commits) that alter the upstream source to the required state. You can freely push and pull from B during this. Just before uploading, you debrebase @@ -434,10 +434,10 @@ If you want to skip dgit's checks while iterating on a problem with the package build (for example, you don't want to commit your changes to git), you can just run dpkg-buildpackage(1) or debuild(1) instead. -=head2 Laundering the patch queue before uploading +=head2 Laundering the delta queue before uploading Just before you B or B, you might want to -have git-debrebase(1) shuffle your branch such that the Debian patch +have git-debrebase(1) shuffle your branch such that the Debian delta queue appears at the end: =over 4 @@ -496,7 +496,7 @@ probably want to debrebase before your next upload to tidy those up. For example, the NMUer might have used git-revert(1) to unapply one of your patches. A debrebase will strip both the patch and the reversion -from the patch series. +from the delta queue. =head1 SEE ALSO -- cgit v1.2.3 From 4e55b79ad5c63c08ae88c4966a4ec0a2c4e675b5 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Tue, 3 Apr 2018 11:05:24 -0700 Subject: dgit-maint-debrebase(7): fix NMUs section Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index f46944f..68127b9 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -485,9 +485,24 @@ option detailed in gbp-import-orig(1). =head1 INCORPORATING NMUS +In the simplest case, + +=over 4 + + % dgit fetch + % git merge --ff-only dgit/dgit/sid + +=back + +If that fails, because your branch and the NMUers work represent +divergent branches of development, you have a number of options. Here +we describe the two simplest. + +=head2 Rebasing your work onto the NMU + =over 4 - % dgit pull + % git rebase dgit/dgit/sid =back @@ -498,6 +513,13 @@ For example, the NMUer might have used git-revert(1) to unapply one of your patches. A debrebase will strip both the patch and the reversion from the delta queue. +=head2 Manually applying the debdiff + +If you cannot rebase because you have already pushed to +B, say, you can manually apply the NMU debdiff, +commit and debrebase. The next B will require +I<--overwrite>. + =head1 SEE ALSO dgit(1), dgit(7) -- cgit v1.2.3 From 233d2b5eea7060eebff598c9edfa5ae659cb7a77 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Tue, 3 Apr 2018 11:05:30 -0700 Subject: dgit-maint-debrebase(7): avoiding merges Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 68127b9..0b75d58 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -55,8 +55,9 @@ This workflow is appropriate for packages where the Debian delta contains multiple pieces which interact, or which you don't expect to be able to upstream soon. For packages with simple and/or short-lived Debian deltas, use of git-debrebase(1) might introduce unneeded -complexity (for examples, see "BEHAVIOUR TO AVOID" below). For such -packages, consider the workflow described in dgit-maint-merge(7). +complexity -- in particular, you cannot use B to +incorporate changes from other contributors. For such packages, +consider the workflow described in dgit-maint-merge(7). =head1 INITIAL DEBIANISATION @@ -270,6 +271,25 @@ I<--deliberately-not-fast-forward> instead of I<--overwrite>. This avoids introducing a new origin commit into your git history. (This origin commit would represent the most recent non-dgit upload of the package, but this should already be represented in your git history.) +=head1 GIT CONFIGURATION + +This workflow does not support using B to merge divergent +branches of development (see "OTHER MERGES" in git-debrebase(5)). You +should configure git such that B does not try to merge: + +=over 4 + + % git config --local pull.rebase true + +=back + +Now when you pull work from other Debian contributors, git will rebase +your work on top of theirs. + +If you use this repository for upstream development in addition to +Debian packaging work, you may not want to set this global setting. +Instead, see the B and +BnameE.rebase> settings in git-config(5). =head1 IMPORTING NEW UPSTREAM RELEASES -- cgit v1.2.3 From 70955b803c88299a945bc9f9d96a7846314ced03 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Tue, 3 Apr 2018 11:07:19 -0700 Subject: dgit-maint-debrebase(7): it's an example Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 0b75d58..cd470ce 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -55,9 +55,9 @@ This workflow is appropriate for packages where the Debian delta contains multiple pieces which interact, or which you don't expect to be able to upstream soon. For packages with simple and/or short-lived Debian deltas, use of git-debrebase(1) might introduce unneeded -complexity -- in particular, you cannot use B to -incorporate changes from other contributors. For such packages, -consider the workflow described in dgit-maint-merge(7). +complexity -- for example, you cannot use B to incorporate +changes from other contributors. For such packages, consider the +workflow described in dgit-maint-merge(7). =head1 INITIAL DEBIANISATION -- cgit v1.2.3 From 70e66ac5c689cf699f3d7577a3d0b74ef16bb300 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Tue, 3 Apr 2018 11:31:45 -0700 Subject: dgit-maint-debrebase(7): make the wood visible despite the trees Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 175 +++++++++++++++++++++++++-------------------- 1 file changed, 99 insertions(+), 76 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index cd470ce..bdfdc8b 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -54,10 +54,9 @@ maintain Debian source packages which use that format. This workflow is appropriate for packages where the Debian delta contains multiple pieces which interact, or which you don't expect to be able to upstream soon. For packages with simple and/or short-lived -Debian deltas, use of git-debrebase(1) might introduce unneeded -complexity -- for example, you cannot use B to incorporate -changes from other contributors. For such packages, consider the -workflow described in dgit-maint-merge(7). +Debian deltas, use of git-debrebase(1) introduces unneeded complexity. +For such packages, consider the workflow described in +dgit-maint-merge(7). =head1 INITIAL DEBIANISATION @@ -94,12 +93,8 @@ something like this: =back Now go ahead and Debianise your package. Just make commits on the -master branch, adding things in the I directory. If you need -to patch the upstream source, see "EDITING THE DELTA QUEUE", below. -Note that there is no need to maintain a separate 'upstream' branch, -unless you also happen to be involved in upstream development. We -work with upstream tags rather than any branches, except temporary -branches used to prepare patches for forwarding upstream, for example. +master branch, adding things in the I directory, or patching +the upstream source. Finally, you need an orig tarball: @@ -194,7 +189,7 @@ it somewhere. The usual choice is B: =back You are now ready to proceed as above, making commits to the -I directory. +I directory and to the upstream source. =head1 CONVERTING AN EXISTING PACKAGE @@ -265,12 +260,8 @@ To achieve this, you might need to delete I. One way to have dgit check your progress is to run B. -The first dgit push will require I<--overwrite>. If this is the first -ever dgit push of the package, consider passing -I<--deliberately-not-fast-forward> instead of I<--overwrite>. This -avoids introducing a new origin commit into your git history. (This -origin commit would represent the most recent non-dgit upload of the -package, but this should already be represented in your git history.) +The first dgit push will require I<--overwrite>. + =head1 GIT CONFIGURATION This workflow does not support using B to merge divergent @@ -293,6 +284,9 @@ BnameE.rebase> settings in git-config(5). =head1 IMPORTING NEW UPSTREAM RELEASES +There are two steps: obtaining git refs that correspond to the new +release, and importing that release using git-debrebase(1). + =head2 Obtaining the release =head3 When upstream tags releases in git @@ -378,28 +372,7 @@ edit, re-order and delete patches. Run =back to start an interactive rebase. You can edit, re-order and delete -commits just as you would during B. Alternatively, you -can perform a non-interactive rebase like this: - -=over 4 - - % git debrebase -- [git-rebase options...] - -=back - -A third alternative is to have git-debrebase(1) shuffle all the Debian -changes to the end of your branch, and then manipulate them yourself -using git-rebase(1). For example, - -=over 4 - - % git debrebase launder - % git rebase -i HEAD~5 # there are 4 Debian patches - -=back - -If you take this approach, you should be very careful not to start the -rebase earlier than the beginning of the delta queue. +commits just as you would during B. =head2 Editing patches: finishing a debrebase @@ -414,51 +387,27 @@ git remote such as B, =over 4 - % git debrebase launder - % git debrebase stitch + % git debrebase conclude =back -Note that each time you stitch a debrebase you introduce a pseudomerge -into your git history, which may make it harder to read. Try to do -all of the editing of the delta queue that you think will be needed -for this upload in a single debrebase, so that there is a single -debrebase stitch. - -A strategy is to debrebase only right before you upload. Before that -point, instead of editing the existing delta queue, you append fixup -commits (and reversions of commits) that alter the upstream source to -the required state. You can freely push and pull from -B during this. Just before uploading, you debrebase -to tidy everything up. +Note that each time you conclude a debrebase you introduce a +pseudomerge into your git history, which may make it harder to read. +Try to do all of the editing of the delta queue that you think will be +needed for this upload in a single debrebase, so that there is a +single debrebase stitch. =head1 BUILDING AND UPLOADING -Use B, B, B and B as detailed in dgit(1). If any command fails, dgit will -provide a carefully-worded error message explaining what you should -do. If it's not clear, file a bug against dgit. Remember to pass -I<--new> for the first upload. - -After dgit pushing, be sure to git push to B, if -you're using that. +You can use dpkg-buildpackage(1) for test builds. When you are ready +to build for an upload, use B. -As an alternative to B and friends, you can use a tool -like gitpkg(1). This works because like dgit, gitpkg(1) enforces that -HEAD has exactly the contents of the source package. gitpkg(1) is -highly configurable, and one dgit user reports using it to produce and -test multiple source packages, from different branches corresponding -to each of the current Debian suites. +Upload with B or B. Remember to pass +I<--new> if the package is new in the target suite. -If you want to skip dgit's checks while iterating on a problem with -the package build (for example, you don't want to commit your changes -to git), you can just run dpkg-buildpackage(1) or debuild(1) instead. - -=head2 Laundering the delta queue before uploading - -Just before you B or B, you might want to -have git-debrebase(1) shuffle your branch such that the Debian delta -queue appears at the end: +Right before uploading, if you did not just already do so, you might +want to have git-debrebase(1) shuffle your branch such that the Debian +delta queue appears right at the tip of the branch you will push: =over 4 @@ -469,6 +418,9 @@ queue appears at the end: Note that this will introduce a new pseudomerge. +After dgit pushing, be sure to git push to B, if +you're using that. + =head1 HANDLING DFSG-NON-FREE MATERIAL This covers only DFSG-non-free material. Material which is legally @@ -540,6 +492,77 @@ B, say, you can manually apply the NMU debdiff, commit and debrebase. The next B will require I<--overwrite>. +=head1 HINTS AND TIPS + +=head2 Minimising pseudomerges + +Above we noted that each time you conclude a debrebase, you introduce +a pseudomerge into your git history, which may make it harder to read. + +A convention you can use to minimise the number of pseudomerges is to +debrebase only right before you upload. + +Before that point, instead of editing the existing delta queue, you +append fixup commits (and reversions of commits) that alter the +upstream source to the required state. You can freely push and pull +from B during this. Just before uploading, you +debrebase, once, to tidy everything up. + +=head2 Upstream branches + +Except in the case where upstream releases only tarballs, we do not +maintain a separate 'upstream' branch (unless you also happen to be +involved in upstream development). We work with upstream tags rather +than any branches, except temporary branches used to prepare patches +for forwarding upstream, for example. + +The thought behind this is that branches are things to which one +expects to commit, while tags are immutable points in history. From +the Debian point of the view, the upstream source is immutable. It's +our packaging to which we expect to commit. + +=head2 The first ever dgit push + +If this is the first ever dgit push of the package, consider passing +I<--deliberately-not-fast-forward> instead of I<--overwrite>. This +avoids introducing a new origin commit into your git history. (This +origin commit would represent the most recent non-dgit upload of the +package, but this should already be represented in your git history.) + +=head2 Alternative ways to start a debrebase + +Above we started an interactive debrebase by invoking git-debrebase(1) +without any arguments, i.e. + +=over 4 + + % git debrebase + +=back + +It is also possible to perform a non-interactive rebase, like this: + +=over 4 + + % git debrebase -- [git-rebase options...] + +=back + + +A third alternative is to have git-debrebase(1) shuffle all the Debian +changes to the end of your branch, and then manipulate them yourself +using git-rebase(1) directly. For example, + +=over 4 + + % git debrebase launder + % git rebase -i HEAD~5 # there are 4 Debian patches + +=back + +If you take this approach, you should be very careful not to start the +rebase earlier than the beginning of the delta queue. + =head1 SEE ALSO dgit(1), dgit(7) -- cgit v1.2.3 From 1dc6dbb264507f20e0afa3217583c0bfe1dd635f Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Wed, 18 Apr 2018 14:29:24 -0700 Subject: dgit-maint-debrebase(7): first commit to new package must introduce debian/ and nothing else Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index bdfdc8b..6c0cf17 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -92,9 +92,12 @@ something like this: =back -Now go ahead and Debianise your package. Just make commits on the -master branch, adding things in the I directory, or patching -the upstream source. +Now go ahead and Debianise your package. Make commits on the master +branch, adding things in the I directory, or patching the +upstream source. For technical reasons, B In other words, make a commit +introducing I before patching the upstream source. Finally, you need an orig tarball: @@ -189,7 +192,12 @@ it somewhere. The usual choice is B: =back You are now ready to proceed as above, making commits to the -I directory and to the upstream source. +I directory and to the upstream source. As above, for +technical reasons, B In other words, make a commit introducing I before +patching the upstream source. + =head1 CONVERTING AN EXISTING PACKAGE -- cgit v1.2.3 From cdd873c0a2e5a7dc3df089722ded0dbff57c53f2 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Wed, 18 Apr 2018 14:31:35 -0700 Subject: dgit-maint-debrebase(7): Verifying->Comparing Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 6c0cf17..f25fe57 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -112,7 +112,7 @@ See git-deborig(1) if this fails. This tarball is ephemeral and easily regenerated, so we don't commit it anywhere (e.g. with tools like pristine-tar(1)). -=head3 Verifying upstream's tarball releases +=head3 Comparing upstream's tarball releases =over 4 -- cgit v1.2.3 From f9897ea4eba03411622873e66dc7c86b680a1a02 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Wed, 18 Apr 2018 14:49:45 -0700 Subject: dgit-maint-debrebase(7): respond to feedback Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 70 +++++++++++++++++++++------------------------- 1 file changed, 32 insertions(+), 38 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index f25fe57..9e22cd1 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -116,23 +116,29 @@ it anywhere (e.g. with tools like pristine-tar(1)). =over 4 -It can be a good idea to compare upstream's released tarballs with the -release tags, at least for the first upload of the package. If they -are different, you might need to add some additional steps to your -I, such as running autotools. +The above assumes that you know how to build the package from git and +that doing so is straightforward. -A convenient way to perform this check is to import the tarball as -described in the following section, using a different value for -'upstream-tag', and then use git-diff(1) to compare the imported -tarball to the release tag. If they are the same, you can use -upstream's tarball instead of running git-deborig(1). +If, as a user of the upstream source, you usually build from upstream +tarball releases, rather than upstream git tags, you will sometimes +find that the git tree doesn't contain everything that is in the +tarball. + +Additional build steps may be needed. For example, you may need your +I to run autotools. + +You can compare the upstream tarball release, and upstream git tag, +within git, by importing the tarball into git as described in the +next section, using a different value for 'upstream-tag', and then +using git-diff(1) to compare the imported tarball to the release tag. =back =head2 When upstream releases only tarballs -We need a virtual upstream branch with virtual release tags. -gbp-import-orig(1) can manage this for us. To begin +Because we want to work in git, we need a virtual upstream branch with +virtual release tags. gbp-import-orig(1) can manage this for us. To +begin =over 4 @@ -198,7 +204,6 @@ the debian/ directory containing at least one file, and does nothing else.> In other words, make a commit introducing I before patching the upstream source. - =head1 CONVERTING AN EXISTING PACKAGE This section explains how to convert an existing Debian package to @@ -236,17 +241,6 @@ corresponding to each of the quilt patches. You can use =back -or manually with gbp-pq(1): - -=over 4 - - % gbp pq import - % gbp pq switch - % git merge --ff-only patch-queue/master - % gbp pq drop - -=back - Then make new upstream tags available: =over 4 @@ -255,14 +249,10 @@ Then make new upstream tags available: =back -=for dgit-test dpkg-source-ignores begin - Now you simply need to ensure that your git HEAD is dgit-compatible, -i.e., it is exactly what you would get if you ran -B -and then unpacked the resultant source package. - -=for dgit-test dpkg-source-ignores end +i.e., it is exactly what you would get if you deleted .git, invoked +B, and then unpacked the resultant source +package. To achieve this, you might need to delete I. One way to have dgit check your @@ -272,9 +262,10 @@ The first dgit push will require I<--overwrite>. =head1 GIT CONFIGURATION -This workflow does not support using B to merge divergent -branches of development (see "OTHER MERGES" in git-debrebase(5)). You -should configure git such that B does not try to merge: +git-debrebase does not yet support using B to merge +divergent branches of development (see "OTHER MERGES" in +git-debrebase(5)). You should configure git such that B +does not try to merge: =over 4 @@ -285,7 +276,7 @@ should configure git such that B does not try to merge: Now when you pull work from other Debian contributors, git will rebase your work on top of theirs. -If you use this repository for upstream development in addition to +If you use this clone for upstream development in addition to Debian packaging work, you may not want to set this global setting. Instead, see the B and BnameE.rebase> settings in git-config(5). @@ -333,12 +324,15 @@ or if you have a working watch file =over 4 % git debrebase new-upstream-v0 1.2.3 - % dch -v1.2.3-1 New upstream release. - % git add debian/changelog && git commit -m changelog =back -You can now review the merge of the new upstream release: +This invocation of git-debrebase(1) involves a git rebase. You may +need to resolve conflicts if the Debian delta queue does not apply +cleanly to the new upstream source. + +If all went well, you can now review the merge of the new upstream +release: =over 4 @@ -366,7 +360,7 @@ a tarball: Adding new patches is straightforward: just make commits touching only files outside of the I directory. You can also use tools -like git-revert(1), git-am(1) and git-cherrypick(1). +like git-revert(1), git-am(1) and git-cherry-pick(1). =head2 Editing patches: starting a debrebase -- cgit v1.2.3 From 79541dbbdc8572e1168635f911f46a625600747c Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Wed, 18 Apr 2018 16:37:55 -0700 Subject: dgit-maint-debrebase(7): fix desc. of convert-from-gbp cmd Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 9e22cd1..87c48ff 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -232,8 +232,8 @@ and obtain the corresponding orig.tar from the archive: =back -If your tree is patches-unapplied, you will need to make a commit -corresponding to each of the quilt patches. You can use +If your tree is patches-unapplied, some conversion work is needed. +You can use =over 4 -- cgit v1.2.3 From 5508805cacec58328bb8c65e81f906c39c60fe1a Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Wed, 18 Apr 2018 16:38:19 -0700 Subject: dgit-maint-debrebase(7): add "EDITING THE DEBIAN PACKAGING" Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 87c48ff..1ff03b7 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -354,6 +354,10 @@ a tarball: =back +=head1 EDITING THE DEBIAN PACKAGING + +Just make commits on master that change the contents of I. + =head1 EDITING THE DELTA QUEUE =head2 Adding new patches -- cgit v1.2.3 From 0c173ee9dca1fb60f33b4b0138914a0183dc4bd8 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Wed, 18 Apr 2018 16:38:37 -0700 Subject: dgit-maint-debrebase(7): fix debrebase invocations Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 1ff03b7..599b6c7 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -373,7 +373,7 @@ edit, re-order and delete patches. Run =over 4 - % git debrebase + % git debrebase -i =back @@ -417,7 +417,7 @@ delta queue appears right at the tip of the branch you will push: =over 4 - % git debrebase launder + % git debrebase % dgit push-source =back @@ -538,11 +538,11 @@ package, but this should already be represented in your git history.) =head2 Alternative ways to start a debrebase Above we started an interactive debrebase by invoking git-debrebase(1) -without any arguments, i.e. +like this: =over 4 - % git debrebase + % git debrebase -i =back -- cgit v1.2.3 From 36b821c4a7a359d99034c4d53d7bd4ac87be5192 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Wed, 18 Apr 2018 16:38:47 -0700 Subject: dgit-maint-debrebase(7): simplify hint about manual rebase Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 599b6c7..7ffeaef 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -567,7 +567,7 @@ using git-rebase(1) directly. For example, =back If you take this approach, you should be very careful not to start the -rebase earlier than the beginning of the delta queue. +rebase too early. =head1 SEE ALSO -- cgit v1.2.3 From 9f04e19a184b812d8643b6e712bf4106648ca7bf Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Wed, 18 Apr 2018 16:39:05 -0700 Subject: dgit-maint-debrebase(7): drop claims about purpose of branches Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 7ffeaef..a2ae3f8 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -522,10 +522,8 @@ involved in upstream development). We work with upstream tags rather than any branches, except temporary branches used to prepare patches for forwarding upstream, for example. -The thought behind this is that branches are things to which one -expects to commit, while tags are immutable points in history. From -the Debian point of the view, the upstream source is immutable. It's -our packaging to which we expect to commit. +The thought behind this is that from Debian's point of view, upstream +releases are immutable points in history, better represented by tags. =head2 The first ever dgit push -- cgit v1.2.3 From 7ba46bbf3be9e1bb01cfa50e46ec2f67a46b6eda Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Wed, 18 Apr 2018 16:39:19 -0700 Subject: dgit-maint-debrebase(7): correct what debrebase will do when debrebasing an NMU Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index a2ae3f8..f5023e8 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -488,8 +488,8 @@ If the NMUer added new commits modifying the upstream source, you will probably want to debrebase before your next upload to tidy those up. For example, the NMUer might have used git-revert(1) to unapply one of -your patches. A debrebase will strip both the patch and the reversion -from the delta queue. +your patches. A debrebase can be used to strip both the patch and the +reversion from the delta queue. =head2 Manually applying the debdiff -- cgit v1.2.3 From 6c71be2adc4988866fdaef4d1dd31fd75bc5fb21 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Wed, 18 Apr 2018 17:03:20 -0700 Subject: dgit-maint-debrebase(7): improve advice about minimising stitches Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index f5023e8..601b8e9 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -400,8 +400,8 @@ git remote such as B, Note that each time you conclude a debrebase you introduce a pseudomerge into your git history, which may make it harder to read. Try to do all of the editing of the delta queue that you think will be -needed for this upload in a single debrebase, so that there is a -single debrebase stitch. +needed for this editing session in a single debrebase, so that there +is a single debrebase stitch. =head1 BUILDING AND UPLOADING @@ -505,12 +505,15 @@ I<--overwrite>. Above we noted that each time you conclude a debrebase, you introduce a pseudomerge into your git history, which may make it harder to read. -A convention you can use to minimise the number of pseudomerges is to -debrebase only right before you upload. +A simple convention you can use to minimise the number of pseudomerges +is to B only right before you upload or push +to B. -Before that point, instead of editing the existing delta queue, you +It is possible to reduce the number of pseudomerges further by +derebasing only (i) when importing a new release, and (ii) right +before uploading. Instead of editing the existing delta queue, you append fixup commits (and reversions of commits) that alter the -upstream source to the required state. You can freely push and pull +upstream source to the required state. You can push and pull to and from B during this. Just before uploading, you debrebase, once, to tidy everything up. -- cgit v1.2.3 From ce81728bbbad2adfd4fbdd32467acec87eca5b3d Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Wed, 18 Apr 2018 17:06:20 -0700 Subject: dgit-maint-debrebase(7): notes about d/patches Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 601b8e9..c615ce2 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -476,6 +476,10 @@ If that fails, because your branch and the NMUers work represent divergent branches of development, you have a number of options. Here we describe the two simplest. +Note that you should not try to resolve the divergent branches by +editing files in I. Changes there would either cause +trouble, or be overwritten by git-debrebase(1). + =head2 Rebasing your work onto the NMU =over 4 @@ -517,6 +521,13 @@ upstream source to the required state. You can push and pull to and from B during this. Just before uploading, you debrebase, once, to tidy everything up. +=head2 The debian/patches directory + +In this workflow, I is purely an output of +git-debrebase(1). You should not make changes there. They will +either cause trouble, or be ignored and overwritten by +git-debrebase(1). + =head2 Upstream branches Except in the case where upstream releases only tarballs, we do not -- cgit v1.2.3 From 0824695592eda56d0505f891aaf18db40958f0d7 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Thu, 19 Apr 2018 09:13:46 -0700 Subject: dgit-maint-debrebase(7): respond to feedback on DFSG-non-free section Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 47 ++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 39 insertions(+), 8 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index c615ce2..b17833e 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -429,9 +429,11 @@ you're using that. =head1 HANDLING DFSG-NON-FREE MATERIAL -This covers only DFSG-non-free material. Material which is legally -dangerous (for example, files which are actually illegal) cannot be -handled this way. +=head2 Illegal material + +Here we explain how to handle material that is merely DFSG-non-free. +Material which is legally dangerous (for example, files which are +actually illegal) cannot be handled this way. If you encounter possibly-legally-dangerous material in the upstream source code you should seek advice. It is often best not to make a @@ -439,22 +441,51 @@ fuss on a public mailing list (at least, not at first). Instead, email your archive administrators. For Debian that is To: dgit-owner@debian.org, ftpmaster@ftp-master.debian.org -=head2 When upstream tags releases in git +=head2 DFSG-non-free: When upstream tags releases in git + +Our approach is to maintain a DFSG-clean upstream branch, and create +tags on this branch for each release that we want to import. We then +import those tags per "Importing the release", above. -We create a DFSG-clean tag to import to master: +For the first upstream release that requires DFSG filtering: =over 4 - % git checkout -b pre-dfsg 1.2.3 + % git checkout -b upstream-dfsg 1.2.3 % git rm evil.bin % git commit -m "upstream version 1.2.3 DFSG-cleaned" % git tag -s 1.2.3+dfsg % git checkout master - % git branch -D pre-dfsg + % # proceed with "Importing the release" =back -=head2 When upstream releases only tarballs +And for subsequent releases (whether or not they require filtering): + +=over 4 + + % git checkout upstream-dfsg + % git merge 1.2.4 + % git rm further-evil.bin # if needed + % git commit -m "upstream version 1.2.4 DFSG-cleaned" + % git tag -s 1.2.4+dfsg + % git checkout master + % # proceed with "Importing the release" + +=back + +Our upstream-dfsg branch cannot be pushed to B, but since +we will need it whenever we import a new upstream version, we must +push it somewhere. Assuming that you have already set up an origin +remote per the above, + +=over 4 + + % git push --follow-tags -u origin master upstream-dfsg + +=back + +=head2 DFSG-non-free: When upstream releases only tarballs The easiest way to handle this is to add a B field to I, and a B setting in -- cgit v1.2.3 From 944f532e615c416a2dd16a617f948b2f89a6f0de Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Thu, 19 Apr 2018 09:19:55 -0700 Subject: dgit-maint-debrebase(7): further notes about d/patches Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index b17833e..6d14c0b 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -559,6 +559,12 @@ git-debrebase(1). You should not make changes there. They will either cause trouble, or be ignored and overwritten by git-debrebase(1). +I will often be out-of-date because git-debrebase(1) +will only regenerate it when it needs to. So you should not rely on +the information in that directory. When preparing patches to forward +upstream, you should use git-format-patch(1) on git commits, rather +than sending files from I. + =head2 Upstream branches Except in the case where upstream releases only tarballs, we do not -- cgit v1.2.3 From 0df581dab31cc84a16974992d3c449197a2c00b3 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Thu, 19 Apr 2018 09:20:49 -0700 Subject: dgit-maint-debrebase(7): improve "Upstream branches" Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 6d14c0b..e78f5f2 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -567,14 +567,15 @@ than sending files from I. =head2 Upstream branches -Except in the case where upstream releases only tarballs, we do not -maintain a separate 'upstream' branch (unless you also happen to be -involved in upstream development). We work with upstream tags rather -than any branches, except temporary branches used to prepare patches -for forwarding upstream, for example. - -The thought behind this is that from Debian's point of view, upstream -releases are immutable points in history, better represented by tags. +Except in the case where upstream releases only tarballs, or we +require DFSG filtering, we do not maintain a separate 'upstream' +branch (unless you also happen to be involved in upstream +development). We work with upstream tags rather than any branches +(except temporary branches used to prepare patches for forwarding +upstream, for example). + +The idea here is that from Debian's point of view, upstream releases +are immutable points in history, and so better represented by tags. =head2 The first ever dgit push -- cgit v1.2.3 From 195e21c55a52a651d66e5d7278b5feb0cb5ebfab Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Thu, 19 Apr 2018 09:25:07 -0700 Subject: dgit-maint-debrebase(7): downgrade very minimal debrebasing workflow yet further Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index e78f5f2..ec58507 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -544,13 +544,13 @@ A simple convention you can use to minimise the number of pseudomerges is to B only right before you upload or push to B. -It is possible to reduce the number of pseudomerges further by -derebasing only (i) when importing a new release, and (ii) right -before uploading. Instead of editing the existing delta queue, you -append fixup commits (and reversions of commits) that alter the -upstream source to the required state. You can push and pull to and -from B during this. Just before uploading, you -debrebase, once, to tidy everything up. +It is possible, though much less convenient, to reduce the number of +pseudomerges yet further. We debrebase only (i) when importing a new +release, and (ii) right before uploading. Instead of editing the +existing delta queue, you append fixup commits (and reversions of +commits) that alter the upstream source to the required state. You +can push and pull to and from B during this. Just +before uploading, you debrebase, once, to tidy everything up. =head2 The debian/patches directory -- cgit v1.2.3 From a090117492eafad326684b0dc49f73184f52d148 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Thu, 19 Apr 2018 09:25:49 -0700 Subject: dgit-maint-debrebase(7): be consistent about referring to the tool Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index ec58507..3c6e2fd 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -262,7 +262,7 @@ The first dgit push will require I<--overwrite>. =head1 GIT CONFIGURATION -git-debrebase does not yet support using B to merge +git-debrebase(1) does not yet support using B to merge divergent branches of development (see "OTHER MERGES" in git-debrebase(5)). You should configure git such that B does not try to merge: -- cgit v1.2.3 From 130db7d9bae45f6a5777c841dd97356b7335a98c Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Thu, 19 Apr 2018 09:32:33 -0700 Subject: dgit-maint-debrebase(7): add another "# if needed" Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 3c6e2fd..fb7c1e1 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -467,7 +467,7 @@ And for subsequent releases (whether or not they require filtering): % git checkout upstream-dfsg % git merge 1.2.4 % git rm further-evil.bin # if needed - % git commit -m "upstream version 1.2.4 DFSG-cleaned" + % git commit -m "upstream version 1.2.4 DFSG-cleaned" # if needed % git tag -s 1.2.4+dfsg % git checkout master % # proceed with "Importing the release" -- cgit v1.2.3 From 475f3383221e1bf091ef124d0afde436d9c25bca Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Thu, 19 Apr 2018 09:35:30 -0700 Subject: dgit-maint-debrebase(7): tweak instructions to import DFSG-clean tag Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index fb7c1e1..297bf48 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -456,7 +456,7 @@ For the first upstream release that requires DFSG filtering: % git commit -m "upstream version 1.2.3 DFSG-cleaned" % git tag -s 1.2.3+dfsg % git checkout master - % # proceed with "Importing the release" + % # proceed with "Importing the release" on 1.2.3+dfsg tag =back @@ -470,7 +470,7 @@ And for subsequent releases (whether or not they require filtering): % git commit -m "upstream version 1.2.4 DFSG-cleaned" # if needed % git tag -s 1.2.4+dfsg % git checkout master - % # proceed with "Importing the release" + % # proceed with "Importing the release" on 1.2.4+dfsg tag =back -- cgit v1.2.3 From dbc28f02cedbfcdc28f052235bef28820cd5a9a8 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Thu, 19 Apr 2018 09:27:05 -0700 Subject: dgit-maint-merge(7): recommend dgit-maint-debrebase(7) Signed-off-by: Sean Whitton --- dgit-maint-merge.7.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod index 2674d66..a02e1fd 100644 --- a/dgit-maint-merge.7.pod +++ b/dgit-maint-merge.7.pod @@ -42,7 +42,7 @@ or which you aren't going to be able to upstream soon, it might be preferable to maintain the delta as a rebasing patch series. For such a workflow see for example -dgit-maint-gbp(7). +dgit-maint-debrebase(7) and dgit-maint-gbp(7). =head1 INITIAL DEBIANISATION -- cgit v1.2.3 From ab8ef34948962d7f30f4ea31a0ea8f5e59b3b742 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Thu, 19 Apr 2018 09:48:41 -0700 Subject: Makefile: add dgit-maint-debrebase.7 to MAN7PAGES Signed-off-by: Sean Whitton --- Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/Makefile b/Makefile index d2a91d8..3eca312 100644 --- a/Makefile +++ b/Makefile @@ -39,6 +39,7 @@ MAN7PAGES=dgit.7 \ dgit-user.7 dgit-nmu-simple.7 \ dgit-maint-native.7 \ dgit-maint-merge.7 dgit-maint-gbp.7 \ + dgit-maint-debrebase.7 \ dgit-sponsorship.7 TXTDOCS=README.dsc-import -- cgit v1.2.3 From 091802332c7d7f3aee0f514b9a9e44b6105163c5 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Thu, 19 Apr 2018 13:14:19 -0700 Subject: dgit-maint-debrebase(7): rewrite "Upstream branches" again Suggested-by: Ian Jackson Signed-off-by: Sean Whitton --- dgit-maint-debrebase.7.pod | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 297bf48..9157ee6 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -567,15 +567,22 @@ than sending files from I. =head2 Upstream branches -Except in the case where upstream releases only tarballs, or we -require DFSG filtering, we do not maintain a separate 'upstream' -branch (unless you also happen to be involved in upstream -development). We work with upstream tags rather than any branches -(except temporary branches used to prepare patches for forwarding -upstream, for example). +In this workflow, we specify upstream tags rather than any branches. + +Except when (i) upstream releases only tarballs, (ii) we require DFSG +filtering, or (iii) you also happen to be involved in upstream +development, we do not maintain any local branch corresponding to +upstream, except temporary branches used to prepare patches for +forwarding, and the like. The idea here is that from Debian's point of view, upstream releases -are immutable points in history, and so better represented by tags. +are immutable points in history. We want to make sure that we are +basing our Debian package on a properly identified upstream version, +rather than some arbitrary commit on some branch. Tags are more +useful for this. + +Upstream's branches remain available as the git remote tracking +branches for your upstream remote, e.g. I. =head2 The first ever dgit push -- cgit v1.2.3 From 62c0cfa46f4bfd4ae0b7cc2cbfbff61f94b14a5e Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Sun, 17 Jun 2018 22:59:46 +0100 Subject: git-debrebase: add dgit-maint-debrebase.7 to .gitignore Signed-off-by: Ian Jackson --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 13e2c4b..a804fa3 100644 --- a/.gitignore +++ b/.gitignore @@ -11,5 +11,6 @@ dgit-nmu-simple.7 dgit-maint-native.7 dgit-maint-merge.7 dgit-maint-gbp.7 +dgit-maint-debrebase.7 dgit-sponsorship.7 substituted -- cgit v1.2.3 From de314c43e38b9043552c9953e7f2fdbf92a0c787 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Sun, 17 Jun 2018 23:01:39 +0100 Subject: dgit-maint-debrebase(7): Add cross-refs to git-debrebase(1) and (5) Signed-off-by: Ian Jackson --- dgit-maint-debrebase.7.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 9157ee6..5ae921f 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -628,7 +628,7 @@ rebase too early. =head1 SEE ALSO -dgit(1), dgit(7) +dgit(1), dgit(7), git-debrebase(1), git-debrebase(5) =head1 AUTHOR -- cgit v1.2.3