control: tag -1 +patch Hello,
On Mon 08 Apr 2019 at 03:43PM +01, Ian Jackson wrote: > Package: git-debrebase > Version: 8.4 > > Sam Hartman wrote the following me in private email. It is a apposite > (and sadly hilarious) critique of the documentation. I am filing it > here as a bug, with permission. At our recent sprint I'd said I'd triage this bug. Reading the discussion again, I think I've come up with a patch which improves things quite a bit. -- Sean Whitton
From eb494b39bf6dd6edb37b32b61fc69f36dfe0e0e2 Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhit...@spwhitton.name>
Date: Sat, 20 Jul 2019 13:00:34 +0100
Subject: [PATCH] git-debrebase(1): Make this manpage a less intimidating entry
point
- Nicer short description right in the first section.
- Don't use the term 'delta queue' until it's needed.
- Don't talk about other manpages so early.
- Cater for people who type `man git-debrebase` looking for a
barebones tutorial, not (just) a command line reference.
- That tutorial should minimise references to dgit, especially since
users might want to use git-debpush to upload.
Closes: #926656
Signed-off-by: Sean Whitton <spwhit...@spwhitton.name>
---
git-debrebase.1.pod | 91 +++++++++++++++++++++++++++++++++++++++++----
1 file changed, 84 insertions(+), 7 deletions(-)
diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index 6f328dd9..96ccfe3e 100644
--- a/git-debrebase.1.pod
+++ b/git-debrebase.1.pod
@@ -1,21 +1,98 @@
=head1 NAME
-git-debrebase - delta queue rebase tool for Debian packaging
+git-debrebase - tool to maintain series of Debian changes to upstream source
=head1 SYNOPSYS
git-debrebase [<options...>] [-- <git-rebase options...>]
git-debrebase [<options...>] <operation> [<operation options...>
-=head1 INTRODUCTION
+=head1 QUICK REFERENCE
-git-debrebase is a tool for representing in git,
-and manpulating,
-Debian packages based on upstream source code.
+=head2 Converting to git-debrebase from another branch layout
+
+Use one of the B<convert-from-*> subcommands.
+
+=head2 Git configuration
+
+Use
+
+=over 4
+
+ % git config --local pull.rebase true
+
+=back
+
+to avoid accidental attempts to merge. You should not try to git
+merge divergent branches of development.
+
+=head2 Importing a new upstream release
+
+Where you have already fetched a git tag from upstream corresponding
+to release 1.2.3,
+
+=over 4
+
+ % git debrebase new-upstream 1.2.3
+
+=back
+
+If your patches do not apply to the new upstream release, you will
+have to resolve a git rebase here.
+
+Then before pushing anywhere or uploading,
+
+=over 4
+
+ % git debrebase conclude
+
+=back
+
+You probably also want to use L<git-deborig(1)> to generate an
+orig.tar from upstream's git tag.
+
+=head2 Adding new patches
+
+L<git-commit(1)>, L<git-cherry-pick(1)> etc.
+
+=head2 Editing patches
+
+Start a debrebase:
+
+=over 4
+
+ % git debrebase -i
+
+=back
+
+Edit the queue of patches in the same way that you'd complete an
+ordinary git rebase.
+
+Then before pushing anywhere or uploading,
+
+=over 4
+
+ % git debrebase conclude
+
+=back
+
+=head2 Incorporating NMUs
+
+In the simplest case,
+
+=over 4
+
+ % dgit fetch
+ % git merge --ff-only dgit/dgit/sid
+
+=back
+
+=head1 GUIDE TO DOCUMENTATION
This is the command line reference.
-Please read the tutorial
-L<dgit-maint-debrebase(7)>.
+There is also a detailed workflow tutorial at
+L<dgit-maint-debrebase(7)>
+(on which the above "QUICK REFERENCE" is based).
For background, theory of operation,
and definitions see L<git-debrebase(5)>.
--
2.20.1
signature.asc
Description: PGP signature
