Sean Whitton writes ("Re: Bug#926656: git-debrebase docs are intimidating"):
> 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.
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.
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.
I'm not really convinced about the pull --rebase. I think it will go
wrong in too many cases.
Ian.
--
Ian Jackson <ijack...@chiark.greenend.org.uk> These opinions are my own.
If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.
