diff options
-rw-r--r-- | .gitignore | 1 | ||||
-rw-r--r-- | Makefile | 1 | ||||
-rw-r--r-- | dgit-maint-native.7.pod | 111 | ||||
-rw-r--r-- | dgit.1 | 1 |
4 files changed, 114 insertions, 0 deletions
@@ -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 @@ -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) @@ -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 |