chiark / gitweb /
dgit-maint-native(7): New manpage
authorIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 30 Oct 2016 23:35:28 +0000 (23:35 +0000)
committerIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 30 Oct 2016 23:36:39 +0000 (23:36 +0000)
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
.gitignore
Makefile
dgit-maint-native.7.pod [new file with mode: 0644]
dgit.1

index d8d27fa..13e2c4b 100644 (file)
@@ -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
index 5d3464b..68c1a02 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
@@ -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 (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