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.
Ian.
-8<-
From: Sam Hartman <hartm...@debian.org>
To: Ian Jackson <ijack...@chiark.greenend.org.uk>
Subject: Re: git debrebase is cool
Date: Sat, 06 Apr 2019 13:01:57 -0400
>>>>> "Ian" == Ian Jackson <ijack...@chiark.greenend.org.uk> writes:
Ian> Did you see dgit-maint-debrebase(7) ?
No.
I'll read it, but before doing so I'll respond with my user hat on:
1) I want to learn about git-debrebase, not about dgit. Dgit is really
scary and I'm told this thing is better than gbp pq.
2) I started with git-debrebase (1) It told me I needed to read
git-debrebase(5) before I had any hope of understanding it. So I went
and looked up how to look at a man 5 page when there is also a man 1
page (OK, I as Sam actually already knew this), and with great
trepidation stopped reading git-debrebase to read this other thing.
3) I started to see a reference to one of those terms from git-debrebase
(1) (anchor), but it tricked me and was just a cross reference to a
detailed branch specification. I don't want to learn a detailed
specification of anything just to go update my patch. Is this going to
be like that time when my friend told me git grafts could solve that
mismerge problem I had and I ended up trying to understand the
gitrepository man page?
4) Then there are diagrams of merge histories. Wait, this is starting
to remind me of the git-rebase man page that I never understood. O,
wait, rebase is in the name. This is not good! And then there is all
this illegal operations stuff!!! Help!
5) Eventually come back to the git-debrebase man page. Wait this really
isn't so bad. I think I might kind of understand things. Except I
totally don't know how to manage my orig tarballs, or my upstream tags
or anything. I guess I can use gbp for that, but then why don't I use
gbp for everything.
To be clear, I appreciate the detailed documentation, data model and
description of invarients. I did find it took me a lot longer to go
through than the gbp documentation, but I'm the kind of person who found
this detail helpful.
But in contranst gbp-pq mentions rebase once. It allows the user to
think they are not going to need to understand any of the more complex
git stuff, where as git-debrebase tells you right there that rebase -i
might be something you want to do often.
And yeah, you and I probably do want to rebase -i quite often.
But there are a lot of people who never understand git that well. I
don't have a handle on the skill of the average DD nor what the tail
looks like. When I joined Debian, the developers I interacted with were
all fairly skilled. And yet watching discussion of git, git-dpm and
dgit in #debian-devel, I think a lot of people find them beyond their
comfort level.
I don't know what the answer is. I don't even know for sure this is a
problem. I know I want to be in a world where I get to be using tools
like git-debrebase or git-dpm. I would rather live in a world where we
all use gbp pq than where we never get to anything uniform, but that
would not be my first choice.
-8<-
--
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.
