dgit-maint-native(7): New manpage

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/.gitignore b/.gitignore
index d8d27faecc05ebb696398c2be6ffc617d4b0855e..13e2c4b1e873f9694d8b5fbbd527800746f6b067 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,7 @@ debian/*.log
 debian/debhelper-build-stamp
 dgit-user.7
 dgit-nmu-simple.7
+dgit-maint-native.7
 dgit-maint-merge.7
 dgit-maint-gbp.7
 dgit-sponsorship.7

diff --git a/Makefile b/Makefile
index 5d3464b69d2ddd2fa8985400bdd62495f84aeb56..68c1a026d3449c6b034b636dff93e6b56d3d59c1 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -37,6 +37,7 @@ MAN1PAGES=dgit.1
 
 MAN7PAGES=dgit.7                               \
        dgit-user.7 dgit-nmu-simple.7           \
+       dgit-maint-native.7                     \
        dgit-maint-merge.7 dgit-maint-gbp.7     \
        dgit-sponsorship.7
 

diff --git a/dgit-maint-native.7.pod b/dgit-maint-native.7.pod
new file mode 100644 (file)
index 0000000..31da00b
--- /dev/null
+++ b/dgit-maint-native.7.pod
@@ -0,0 +1,111 @@
+=head1 NAME
+
+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>.
+
+=over 4
+
+=item
+
+We expect that your git history is fast-forwarding.
+
+=item
+
+You must 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.
+
+=back
+
+=head2 Benefits
+
+=over 4
+
+=item
+
+Benefit from dgit's safety catches.  In particular, ensure that your
+upload always matches exactly your git HEAD.
+
+=item
+
+Provide a better,
+more detailed history
+to downstream dgit users.
+
+=item
+
+Incorporate an NMU with one command.
+
+=back
+
+=head1 FIRST PUSH WITH DGIT
+
+You do not need to do anything special to your tree
+to push with dgit.
+
+Simply prepare your git tree in the usual way, and then:
+
+=over 4
+
+    % dgit -wgf sbuild -A -c sid
+    % dgit -wgf --overwrite push
+
+=back
+
+(Do not make any tags yourself: dgit push will do that.)
+
+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
+non-dgit uploads.
+
+dgit will make a merge commit
+on your branch
+but without making any code changes
+(ie, a pseudo-merge)
+so that your history,
+which will be pushed to the dgit git server,
+is fast forward from the dgit archive view.
+
+=head1 SUBSEQUENT PUSHES
+
+=over 4
+
+    % dgit -wgf push
+
+=back
+
+That's it.
+
+=head1 INCORPORATING AN NMU
+
+=over 4
+
+    % dgit pull
+
+=back
+
+That's it.
+
+Or, if you would prefer to review the changes,
+you can do this:
+
+=over 4
+
+    % dgit fetch
+    % dgit diff HEAD..dgit/dgit/sid
+
+=back
+
+If you do not merge the NMU into your own git history,
+the next push will then require I<--overwrite>.
+
+=head1 SEE ALSO
+
+dgit(1), dgit(7)

diff --git a/dgit.1 b/dgit.1
index 98b525bca0809ae5472822a7a7130def9bac4b80..148bb7f73fd9ed8221e803ae50e2fd364d6aeae0 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -37,6 +37,7 @@ Please read the tutorial(s):
 lb l.
 dgit-user(7)   for users: editing, building and sharing packages
 dgit-nmu-simple(7)     for DDs/DMs: doing a straightforward NMU
+dgit-maint-native(7)   for maintainers of Debian-native packages
 dgit-maint-merge(7)    for maintainers: using a merging git workflow
 dgit-maint-gbp(7)      for maintainers: using git-buildpackage
 dgit-sponsorship(7)    for sponsors and sponsored contributors