chiark / gitweb /
documentation style: "appropriate configuration" as a mass noun
[dgit.git] / dgit-maint-native.7.pod
index 31da00b..792be10 100644 (file)
@@ -4,8 +4,9 @@ dgit - tutorial for package maintainers of Debian-native packages
 
 =head1 INTRODUCTION
 
-This document describes elements of a workflow for maintaining a
-native Debian package using B<dgit>.
+This document describes elements of a workflow for using B<dgit> to
+maintain a Debian package that uses one of the native source formats
+("1.0" & "3.0 (native)").
 
 =over 4
 
@@ -15,12 +16,16 @@ We expect that your git history is fast-forwarding.
 
 =item
 
-You must be prepared to tolerate a small amount of 
+You should be prepared to tolerate a small amount of
 ugliness in your git history
 in the form of merges which stitch
 the dgit-generated archive view
 into your maintainer history.
 
+This is to handle uploads that were not made with dgit,
+such as the uploads you made before switching to this workflow,
+or NMUs.
+
 =back
 
 =head2 Benefits
@@ -60,6 +65,10 @@ Simply prepare your git tree in the usual way, and then:
 
 (Do not make any tags yourself: dgit push will do that.)
 
+You may use B<dgit pbuilder> or B<dgit cowbuilder>
+instead of B<dgit sbuild>;
+see dgit(1) for the syntax of those subcommands.
+
 The --overwrite option tells dgit that you are expecting
 that your git history is not a descendant of the
 history which dgit synthesised from the previous
@@ -73,6 +82,14 @@ so that your history,
 which will be pushed to the dgit git server,
 is fast forward from the dgit archive view.
 
+Alternatively,
+if this was the first ever dgit push of the package,
+you can avoid this merge commit by
+passing C<--deliberately-not-fast-forward>
+instead of C<--overwrite>.
+This avoids introducing a new origin commit into
+your git history.
+
 =head1 SUBSEQUENT PUSHES
 
 =over 4