Bug#1127616: developers-reference: should document using git-debpush to upload

On Wed, 11 Feb 2026 at 13:59:10 +0100, Simon Josefsson wrote:
>Holger Levsen <[email protected]> writes:
>> "pristine-tar: With a new upstream version, tag2upload will generate a
>> fresh orig tarball with git archive (via git-deborig). This is OK, but
>> it may surprise some users. 1106071."
>
>This is probably the toughest nut, and is mostly a matter of opinion if
>pristine-tar is a good pattern and offers anything useful.

I think pristine-tar is a bit of a red herring here, and the real matter 
of opinion is:

1. on one side, some developers/workflows/upstreams place value on having
    the orig.tar.* be the same bytes that were delivered by upstream
    (in particular so we can validate signed tarballs)
    or if that isn't possible for DFSG reasons, at least having the
    orig.tar.* contain everything that upstream delivered in their
    official source release, minus the parts that either copyright law
    or our self-imposed rules require us to remove

2. on the other side, some developers/workflows/upstreams(?) place value
    on having the upstream source code be the same filesystem tree
    ("tree-same") that is in upstream's *git repository*, which might or
    might not be closely related to what they release in tarballs if
    any, minus the parts that either copyright law or our self-imposed
    rules require us to remove

(And at the same time we have a zero-tolerance policy for 
non-DFSG-compliant files, even if not installed or used, which means 
that when the upstream release contains such files we cannot completely 
follow either (1.) *or* (2.).)

For packages where (1.) is valued higher, pristine-tar is one tool that 
can help to make it happen. It is not the only tool: it's the most 
commonly-used, but pristine-lfs is one alternative that I know about, 
and I'm sure there are others. I think we should not mistake use of the 
pristine-tar tool, specifically, for being the same thing as wanting to 
follow model (1.).

I know that the dgit/tag2upload developers are very much in favour of 
(2.), but I also think it would be a mistake to entangle "we want people 
to use dgit/tag2upload" with "we want people to stop trying to use 
something closely resembling upstream tarball releases as the 
preferred/official source code, and instead behave as though upstream 
didn't release an official source artifact" (and indeed, their design 
has been careful to accommodate arbitrary .orig tarballs, as long as 
there is a git branch that is "tree-same").

The big elephant-in-the-room reason for (1.) and (2.) to differ is 
Autotools, but there are many others, like upstream packages that 
expect/require that their package is either being built from git (with 
./.git and history available for `git describe`, which our buildds 
notably don't have) or from a tarball (with extra files like 
./.tarball-version to compensate for not having git history) but not 
some middle ground between those.

I feel like I should also point out here that devref §6.9.8 demands that 
we keep the upstream source release as pristine as possible, including 
build infrastructure for non-Debian OSs.

As I think I've said before, if some project members are going to demand 
that I follow documented best-practice by doing (1.), and other project 
members are going to demand that I follow their view of best-practice by 
doing (2.), then I'm sorry but someone is going to have to be 
disappointed, because it isn't possible to do both at the same time.

>The special debian/changelog handling for backports has always seemed
>odd to me.  I think having in-package changelog files are increasingly
>becoming an obsolete pattern, for the same reasons ChangeLog files are
>now less relevant.

Whether they're an obsolete pattern or not, our packaging system 
requires the changelog, so we can't just ignore its existence.

I believe we also use debian/changelog as a load-bearing part of our 
approach to license compliance: it's our implementation of the 
"prominent notices stating that [we] modified it" and "relevant date" 
from GPL-3 §5a, or similar concepts from other licenses.

     smcv