Web lists-archives.com

Re: Preferred git branch structure when upstream moves from tarballs to git

On Tue, 2019-05-07 at 12:51 +0100, Ian Jackson wrote:
> Ansgar Burchardt writes ("Re: Preferred git branch structure when
> upstream moves from tarballs to git"):
> > Sam Hartman <hartmans@xxxxxxxxxx> writes:
> > > OK, I didn't hear that as an answer but think I'm coming to the
> > > same
> > > conclusion that Ian did after reading your mail.
> > > It sounds like you are talking about having the Debian packaging
> > > in a
> > > separate repository from upstream.
> > > Do I correctly understand the model you are talking about?
> ...
> > I'll point to [1] for what complexity this avoids.  Try explaining
> > that
> > to someone without advanced Git knowledge...
> > 
> >   [1] 
> > https://manpages.debian.org/unstable/git-debrebase/git-debrebase.5.en.html

> In this message you are using the fact that I have written a
> comprehensive data model specification, against me.  This is a
> seriously bad thing to do.

I think you underestimate how much knowledge you require from users
right from the beginning...

So in a way the problem is that the documentation needs to exist.  git-
debrebase or dgit (to a lesser extend) implement a Debian-specific
version control system on top of Git.  git-debrebase makes this most
obvious: the Git history it generates is pretty much unlike anything
you would ever get from regular Git usage (counterexamples welcome), it
mangles your Git commits into a specific format it expects
(laundering), mangles rebased branches into fast-forward merges with
pseudomerges; all this does not happen in regular Git usage.

dgit has less of these problems, but still does things different from
regular git usage (again pseudomerges to make rebases fast-forward for
example); there are other issues as well such as its suggested use for
NMUs feeling rather unfriendly as it moves the packaging to another VCS
than the maintainer uses with a disjoint history...

Sure, dealing with patch series is not nice either way, but I don't
think the added complexity of git-debrebase (or dgit) is worth what it
provides.  Alternatives require less intimiate knowledge of git and
provide a gentler learning curve; some basic patch queue manipulation
even doesn't require special tools at all (adding/removing patches that
already exist in the right format and apply).

Other distributions have intentionally be trying to move to less
distro-specific tools to reduce barrier of entry; dgit and git-
debrebase both move in the opposite direction (more highly distro-
specific tools).

> You should be applauding me for providing serious documentation for
> advanced users.

According to git-debrebase(1) the documentation I referred to is basic

> You should read this manpage in cojnunction with "TERMINOLOGY" in 
> git-debrebase(5), which defines many important terms used here.

"TERMINOLOGY" then refers to most other sections.

> The obvious counter is the (still comprehensive, but user-facing)
> tutorial manpage.  For example,
> https://manpages.debian.org/stretch-backports/dgit/dgit-maint-debrebase.7.en.html#EDITING_THE_DEBIAN_PACKAGING
> et seq.

It illustrates my other main gripe with dgit/git-debrebase: it makes it
harder to share in-progress work, in fact git-debrebase discourages
people from doing so:

| Note that each time you conclude a debrebase you introduce a
| pseudomerge into your git history, which may make it harder to read.

| A simple convention you can use to minimise the number of
| pseudomerges is to git debrebase conclude only right before you
| upload or push to salsa.debian.org. 

Yes, one can avoid some of the problems by pushing a non-fast-forward,
non-interchange branch.  But that differs from the regular workflow
and, again, requires more advanced Git knowledge.

> An equivalently detailed and frank document about dpkg-source would
> be a nightmare.

The concept behind 3.0 (quilt) is much easier to explain: extract
tarballs, optionally apply some patches provided.  With the bonus that
users who have used other distributions before might already know about
most of this which lowers barrier of entry.  Implementation details
like constructing a .dsc are indeed messy.

With most other Debian packaging workflows one can also limit oneself
to more basic Git commands for regular usage, in the most minimalistic
case only commit/push/pull (not even merge); these also match what
users will know if they have used Git at all (be it for packaging in
other distribution, upstream projects, or even just writing their

You might say that git-debrebase is not required, but what about users
that want to contribute to a package maintained using it?  They will
have to deal with the complexity...  This also differs from other
packaging workflows that usually don't make specific tools mandatory.

(Not all tools can always be made optional of course, but one should do
some consideration if one makes new tools mandatory.)