diff options
Diffstat (limited to 'dgit-maint-merge.7.pod')
| -rw-r--r-- | dgit-maint-merge.7.pod | 439 |
1 files changed, 439 insertions, 0 deletions
diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod new file mode 100644 index 0000000..3da1b78 --- /dev/null +++ b/dgit-maint-merge.7.pod @@ -0,0 +1,439 @@ +=head1 NAME + +dgit - tutorial for package maintainers, using a workflow centered around git-merge(1) + +=head1 INTRODUCTION + +This document describes elements of a workflow for maintaining a +non-native Debian package using B<dgit>. The workflow makes the +following opinionated assumptions: + +=over 4 + +=item + +Git histories should be the non-linear histories produced by +git-merge(1), preserving all information about divergent development +that was later brought together. + +=item + +Maintaining convenient and powerful git workflows takes priority over +the usefulness of the raw Debian source package. The Debian archive +is thought of as an output format. + +For example, we don't spend time curating a series of quilt patches. +However, +in straightforward cases, +the information such a series would contain is readily +available from B<dgit-repos>. + +=item + +It is more important to have the Debian package's git history be a +descendent of upstream's git history than to use exactly the orig.tar +that upstream makes available for download. + +=back + +This workflow is less suitable for some packages. +When the Debian delta contains multiple pieces which interact, +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). + +=head1 INITIAL DEBIANISATION + +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. + +=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. If you want to maintain a copy of your packaging +branch on B<alioth.debian.org> in addition to B<dgit-repos>, you can +do something like this: + +=over 4 + + % git remote add -f origin git.debian.org:/git/collab-maint/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<debian/> directory. If you need +to patch the upstream source, just make commits that change files +outside of the I<debian/> directory. It is best to separate commits +that touch I<debian/> from commits that touch upstream source, so that +the latter can be cherry-picked by upstream. + +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<debian/rules>, 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<debian/gbp.conf>: + +=over 4 + + [DEFAULT] + upstream-branch = upstream + debian-branch = master + upstream-tag = %(version)s + + sign-tags = True + pristine-tar = False + pristine-tar-commit = False + +=back + +Then we can import the upstream version: + +=over 4 + + % git add debian/gbp.conf && git commit -m "create gbp.conf" + % gbp import-orig ../foo_1.2.2.orig.tar.xz + +=back + +You are now ready to proceed as above, making commits to both the +upstream source and the I<debian/> directory. + +If you want to maintain a copy of your repository on +B<alioth.debian.org>, you should push both the origin and the upstream +branches: + +=over 4 + + % git remote add -f origin git.debian.org:/git/collab-maint/foo.git + % git push --follow-tags -u origin master upstream + +=back + +=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, dump any existing patch queue: + +=over 4 + + % git rm -rf debian/patches + % git commit -m "drop existing quilt patch queue" + +=back + +Then make new upstream tags available: + +=over 4 + + % git remote add -f upstream https://some.upstream/foo.git + +=back + +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<dpkg-buildpackage +-i\.git/ -I.git -S> and then unpacked the resultant source package. + +To achieve this, you might need to delete +I<debian/source/local-options>. One way to have dgit check your +progress is to run B<dgit build-source>. + +The first dgit push will require I<--overwrite>. + +=head1 SOURCE PACKAGE CONFIGURATION + +=head2 debian/source/options + +We set some source package options such that dgit can transparently +handle the "dropping" and "refreshing" of changes to the upstream +source: + +=over 4 + + single-debian-patch + auto-commit + +=back + +You don't need to create this file if you are using the version 1.0 +source package format. + +=head2 Sample text for debian/source/patch-header + +It is a good idea to explain how a user can obtain a breakdown of the +changes to the upstream source: + +=over 4 + +The Debian packaging of foo is maintained in git, +using the merging workflow described in dgit-maint-merge(7). +There isn't a patch queue that can be represented as a quilt series. + +A detailed breakdown of the changes is available from their +canonical representation - +git commits in the packaging repository. +For example, to see the changes made by the Debian maintainer in the +first upload of upstream version 1.2.3, you could use: + +=over 4 + + % git clone https://git.dgit.debian.org/foo + % cd foo + % git log --oneline 1.2.3..debian/1.2.3-1 -- . ':!debian' + +=back + +(If you have dgit, use `dgit clone foo`, +rather than plain `git clone`.) + +A single combined diff, containing all the changes, follows. + +=back + +Alternatively, this text could be added to README.source. However, +this might distract from more important information present in the +latter file. + +=head1 BUILDING AND UPLOADING + +Use B<dgit build>, B<dgit sbuild>, B<dgit build-source>, and B<dgit +push> 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. + +As an alternative to B<dgit build> 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. + +=head1 NEW UPSTREAM RELEASES + +=head2 When upstream tags releases in git + +It's a good idea to preview the merge of the new upstream release. +First, just check for any new or deleted files that may need +accounting for in your copyright file: + +=over 4 + + % git remote update + % git diff --stat master..1.2.3 -- . ':!debian' + +=back + +You can then review the full merge diff: + +=over 4 + + % git merge-tree `git merge-base master 1.2.3` master 1.2.3 | $PAGER + +=back + +Once you're satisfied with what will be merged, update your package: + +=over 4 + + % git merge 1.2.3 + % dch -v1.2.3-1 New upstream release. + % git add debian/changelog && git commit -m changelog + % git deborig + +=back + +and you are ready to try a build. + +=head2 When upstream releases only tarballs + +You will need the I<debian/gbp.conf> from "When upstream releases only +tarballs", above. + +Then, either + +=over 4 + + % gbp import-orig ../foo_1.2.2.orig.tar.xz + +=back + +or if you have a working watch file + +=over 4 + + % gbp import-orig --uscan + +=back + +=head1 HANDLING DFSG-NON-FREE MATERIAL + +=head2 When upstream tags releases in git + +We create a DFSG-clean tag to merge 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 merging the new 1.2.3+dfsg tag to master, 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<dgit-repos>. + +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<Files-Excluded> field to +I<debian/copyright>, and a B<uversionmangle> setting in +I<debian/watch>. 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, git and dgit will transparently handle "dropping" the patches +that have been forwarded, "retaining" the ones that haven't. + +=head1 INCORPORATING NMUS + +=over 4 + + % dgit pull + +=back + +Alternatively, you can apply the NMU diff to your repository. The +next push will then require I<--overwrite>. + +=head1 SEE ALSO + +dgit(1), dgit(7) + +=head1 AUTHOR + +This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>. It contains contributions from other dgit contributors too - see the dgit copyright file. |