dgit-maint-native(7): New manpage

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

4 files changed, 114 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
index d8d27fa..13e2c4b 100644
--- 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 5d3464b..68c1a02 100644
--- 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
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 98b525b..148bb7f 100644
--- 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