Hello, On Sat 20 Jul 2019 at 05:34PM +01, Ian Jackson wrote:
> Hi. Thanks for this. I'm not entirely convinced. It seems rather, > err, flabby and discursive. It is intimidating in its own way, "do I > need to read all of this for the quick reference" ? > > A quick reference does not need to contain all the caveats and > explanations. For example, we can assume that the reader knows how > git-rebase works and will be unsurprised if they get a conflict during > a new upstream rebase. I'm inclined to agree with this assessment, but it would be useful to hear from Sam's imaginary new user perspective. > How about: > > QUICK REFERENCE > > These are most of the commands you will regularly need: > > % git debrebase -i # edit the queue of patches > % dpkg-buildpackage -uc -b # build test binaries, at any time > % git debrebase conclude && git push # push to eg salsa > % git debrebase conclude && dgit push-source # source-only upload > % git debrebase [-i] new-upstream 1.2.3-1 # uses tag, eg "v1.2.3" > > To add patches, or edit the packaging, just make git commits. > Ignore anything that may appear in debian/patches. > Avoid using "git pull" and "git merge" without "--ff-only". > > See the tutorial manpage dgit-maint-debrebase for how to > convert your branch into the git-debrebase format. Assuming what you're proposing is substituting this for QUICK REFERENCE in my patch, and keeping my other changes, I think this is really good. Just one thing: I find the use of shell comments at the end of lines makes the block of runes difficult to read. I agree that there is the potential for intimidation if they are as spread out as they are in my first patch, though. I've done something in between in the attached. > I'm not really convinced about the pull --rebase. I think it will go > wrong in too many cases. Okay. I think your git pull&merge warning is better than what I had. I've attached an updated patch. -- Sean Whitton
From bb4717950db7d8f1d70425c4511a8e7654ab5bfa 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.
Thanks to Sam Hartman for the user feedback which prompted this and
Ian Jackson for feedback on the content of "QUICK REFERENCE".
Closes: #926656
Signed-off-by: Sean Whitton <spwhit...@spwhitton.name>
---
git-debrebase.1.pod | 47 ++++++++++++++++++++++++++++++++++++++-------
1 file changed, 40 insertions(+), 7 deletions(-)
diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index af6e3646..22672a29 100644
--- a/git-debrebase.1.pod
+++ b/git-debrebase.1.pod
@@ -1,21 +1,54 @@
=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.
+These are most of the commands you will need regularly:
+
+=over 4
+
+=item Edit the queue of patches
+
+% git debrebase -i
+
+=item Build test binaries, at any time
+
+% dpkg-buildpackage -uc -b
+
+=item Push to an ordinary git remote (e.g. Debian's salsa)
+
+% git debrebase conclude && git push
+
+=item Do a source-only upload
+
+% git debrebase conclude && dgit push-source
+
+=item New upstream release (using an upstream tag like 'v1.2.3')
+
+git debrebase [-i] new-upstream 1.2.3
+
+=back
+
+To add patches, or edit the packaging, just make git commits.
+Ignore anything that may appear in debian/patches.
+Avoid using "git pull" and "git merge" without "--ff-only".
+
+See the tutorial manpage L<dgit-maint-debrebase(7)>, section
+"CONVERTING AN EXISTING PACKAGE", for how to convert your branch into
+the git-debrebase format.
+
+=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
