[3dprinter-general] pristine-tar

[Chow Loong Jin]

On Tue, Aug 26, 2014 at 06:04:57PM +0200, Bas Wijnen wrote:
> Hello,
> 
> I haven't been very active lately, but that should change.  After Cura
> was rejected due to nondistributable files, I thought I should use
> pristine-tar and so far haven't found what that does exactly, and how
> (or even why precisely) I should use it.  This isn't documented on our
> wiki-page either, nor was the internet very helpful to me.

The purpose of pristine-tar is to be able to generate identical .orig.tar.*z
tarballs from the git repository, so that one can just clone the repository and
generate a next package for upload without needing to download the previous orig
tarball. Hence, at a minimum, any orig tarball that is uploaded to Debian should
be pristine-tar'd.

The pristine-tar branch consists of a pair of files per stored tarball:
 - $tarball.delta
 - $tarball.id

The .id file references the commit from which the tarball should be generated.
The .delta is a pristine-tar-specific binary delta that tells pristine-tar
exactly how to generate the pristine tarball witha from the referenced commit.
These files are automatically generated when calling "pristine-tar commit
$tarball $commit_id".

gbp is typically used in one of three ways:
 1. Upstream git history is kept separate from packaging repo, and the upstream
    branch consists of tarballs imported via "git import-orig". This is the
    recommended method as per gbp's documentation[1].

 2. "upstream" branch tracks upstream git history, and tags. In this case, just
    store uptsream's pristine tarballs into the pristine-tar folder by using
    "pristine-tar commit $tarball $version_tag". If you need to mangle the
    tarball, create a new dfsg branch that deletes the files you need, generate
    the tarball, and commit it using "pristine-tar commit $tarball dfsg"

 3. Upstream sources not present at all. In that case, just set
    --git-tarball-dir when calling git buildpackage.

I prefer method #1, but I've noticed #2 being used in the team, specifically in
slic3r. I haven't seen #3 being used at all within the team, and I don't think
we have a policy set in place.

> So I'm asking here: for a package such as Cura, what would be the
> purpose of pristine-tar?  To generate a tarball identical to upstream's,
> including non-distributable files, or without them?  Why do I want
> whatever it does?  What should I do to use it?

If upstream's tarball includes non-distributable files, then you'll probably be
uploading a +dfsg.orig.tar.*z tarball, and that's the tarball that must be
generatable from the git repository via pristine-tar.

As for a pristine non-dfsg-compliant upstream tarball, I'd consider that up to
the maintainer. For some of my packages involving tarball manglement, I use git
import-orig to import the pristine upstream tarball into the "upstream" branch
(with corresponding delta in pristine-tar), and then I merge the "upstream"
branch into "dfsg" which strips away the non-distributable files. "dfsg" is then
merged into "master" or "debian" which contains the debian/ folder.

> After I understand it, I'll document it on our wiki page.  I think it is
> very important that this is well-documented, so that people unfamiliar
> with gbp aren't delayed as much as I am with this issue.  (Which isn't
> only due to this, but it's a large part of it.  No matter how easy this
> may seem, it stops me from starting to work on the package.  I'm sure
> I'm not the only one who responds to that by doing other things
> instead.)

Thanks. That'll be very helpful.

[1] http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.html

-- 
Kind regards,
Loong Jin
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: Digital signature
URL: <http://lists.alioth.debian.org/pipermail/3dprinter-general/attachments/20140827/546af697/attachment.sig>