infra: dgit-repos-server: Break out mkscript

[dgit.git] / dgit-maint-merge.7.pod

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
index d9dcb51075fa91ddca8a74c4c5225df7ea5e622d..3da1b78538cd5eba22e805e033d98cde4ce47926 100644 (file)
--- a/dgit-maint-merge.7.pod
+++ b/dgit-maint-merge.7.pod
@@ -16,8 +16,6 @@ Git histories should be the non-linear histories produced by
 git-merge(1), preserving all information about divergent development
 that was later brought together.
 
 git-merge(1), preserving all information about divergent development
 that was later brought together.
 

-If you prefer linear histories, see dgit-maint-rebase(7).
-

 =item
 
 Maintaining convenient and powerful git workflows takes priority over
 =item
 
 Maintaining convenient and powerful git workflows takes priority over


@@ -25,7 +23,9 @@ 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.
 is thought of as an output format.
 
 For example, we don't spend time curating a series of quilt patches.

-However, the information such a series would contain is readily
+However,
+in straightforward cases,
+the information such a series would contain is readily

 available from B<dgit-repos>.
 
 =item
 available from B<dgit-repos>.
 
 =item


@@ -36,22 +36,20 @@ that upstream makes available for download.
 
 =back
 
 
 =back
 

-=head1 GIT CONFIGURATION
-
-Add the following to your ~/.gitconfig to teach git-archive(1) how to
-compress orig tarballs:
-
-=over 4
-
-    [tar "tar.xz"]
-       command = xz -c
-    [tar "tar.gz"]
-       command = gzip -c
-
-=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
 
 
 =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
 =head2 When upstream tags releases in git
 
 Suppose that the latest stable upstream release is 1.2.2, and this has


@@ -67,7 +65,7 @@ been tagged '1.2.2' by upstream.
 
 =back
 
 
 =back
 

-The final command detachs your master branch from the upstream remote,
+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
 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


@@ -92,20 +90,36 @@ 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 when
 forwarding patches (see FORWARDING PATCHES UPSTREAM, below).
 

-Finally, you need an orig tarball.  Generate one with git-archive(1):
+Finally, you need an orig tarball:

 
 =over 4
 
 
 =over 4
 

-    % git archive -o ../foo_1.2.2.orig.tar.xz 1.2.2
+    % git deborig

 
 =back
 
 
 =back
 

-If you are using the version 1.0 source package format, replace 'xz'
-with 'gz'.
+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)).
 
 
 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.
 =head2 When upstream releases only tarballs
 
 We need a virtual upstream branch with virtual release tags.


@@ -124,7 +138,7 @@ Now create I<debian/gbp.conf>:
 =over 4
 
     [DEFAULT]
 =over 4
 
     [DEFAULT]

-    upstream-branch = upsteram
+    upstream-branch = upstream

     debian-branch = master
     upstream-tag = %(version)s
 
     debian-branch = master
     upstream-tag = %(version)s
 


@@ -157,6 +171,50 @@ branches:
 
 =back
 
 
 =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
 =head1 SOURCE PACKAGE CONFIGURATION
 
 =head2 debian/source/options


@@ -175,31 +233,42 @@ source:
 You don't need to create this file if you are using the version 1.0
 source package format.
 
 You don't need to create this file if you are using the version 1.0
 source package format.
 

-=head2 Sample text for README.source
+=head2 Sample text for debian/source/patch-header

 
 

-It is a good idea to explain how a user can obtain a break down of the
+It is a good idea to explain how a user can obtain a breakdown of the

 changes to the upstream source:
 
 =over 4
 
 changes to the upstream source:
 
 =over 4
 

-The Debian packaging of foo is maintained using dgit.  For the sake of
-an efficient workflow, Debian modifications to the upstream source are
-squashed into a single patch, rather than a series of quilt patches.
-To obtain a patch queue for package version 1.2.3-1:
+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
 
 
 =over 4
 

-    # apt-get install dgit
-    % dgit clone foo
+    % git clone https://git.dgit.debian.org/foo

     % cd foo
     % git log --oneline 1.2.3..debian/1.2.3-1 -- . ':!debian'
 
 =back
 
     % cd foo
     % git log --oneline 1.2.3..debian/1.2.3-1 -- . ':!debian'
 
 =back
 

-See dgit(1), dgit(7) and dgit-maint-merge(7) for more information.
+(If you have dgit, use `dgit clone foo`,
+rather than plain `git clone`.)
+
+A single combined diff, containing all the changes, follows.

 
 =back
 
 
 =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
 =head1 BUILDING AND UPLOADING
 
 Use B<dgit build>, B<dgit sbuild>, B<dgit build-source>, and B<dgit


@@ -246,21 +315,21 @@ Once you're satisfied with what will be merged, update your package:
 
 =over 4
 
 
 =over 4
 

-    % git archive ../foo_1.2.3.orig.tar.xz 1.2.3

     % git merge 1.2.3
     % dch -v1.2.3-1 New upstream release.
     % git add debian/changelog && git commit -m changelog
     % 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.
 
 
 =back
 
 and you are ready to try a build.
 

-Again, if you are using the version 1.0 source package format, replace
-'xz' with 'gz'.
-

 =head2 When upstream releases only tarballs
 
 =head2 When upstream releases only tarballs
 

-Either
+You will need the I<debian/gbp.conf> from "When upstream releases only
+tarballs", above.
+
+Then, either

 
 =over 4
 
 
 =over 4
 


@@ -296,7 +365,12 @@ We create a DFSG-clean tag to merge to master:
 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
 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, pass B<--squash> to git-merge(1).
+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
 
 
 =head2 When upstream releases only tarballs
 


@@ -362,4 +436,4 @@ dgit(1), dgit(7)
 
 =head1 AUTHOR
 
 
 =head1 AUTHOR
 

-This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.
+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.