Debian JavaScript maintainers best practice for repacking

Sometimes you have to repack the upstream tarball to remove some stuff. There are several workflows for that, like manually editing the tarball, the git-buildpackage dfsg_clean branch, cleanup scripts ...

The best practice at the moment is to use the Files-Excluded field in debian/copyright. Here is how you do that.

1. Choose a repack suffix

The version string has this format: [epoch:]upstream_version[-debian_revision]. Repacked tarballs are denoted by adding a repack suffix to the upstream_version part of the version string. The repack suffix has this format: [repack_separator]repack_reason[repack_version]. For example +dfsg, where + is repack_separator and dfsg is repack_reason and repack_version is not specified. So a package name like node-parse-glob_3.0.4-1 becomes node-parse-glob_3.0.4+dfsg-1.

In the following, let's assume the chosen repack suffix is +dfsg.

2. Mark the files to exclude

Append to the first section of debian/copyright (no newline inbetween) a single Files-Excluded field with the list of all excluded files:

Files-Excluded: non_dfsg_compliant_file.extension
Comment: reason for exclusion

The Comment field with the reason for exclusion is mandatory as per Debian Policy 12.5.

In the Files-Excluded field you can use the same simplified shell glob syntax of the Files field (see Machine-readable debian/copyright file specification), list files etc.

If more than one file/globbing pattern is required, you can use:

Files-Excluded:
    file_a
    file_b
    file_c
    dist
    ...
Comment: The following files were removed because
  file_a: Binary with no source
  file_b: non-free license
  file_c: just cruft
  dist: only generated files in this directory
  ...

3. Do the actual repack

Add the chosen repack suffix to debian/watch params, for example:

repacksuffix=+dfsg,\
repack,compression=xz,\

Note: xz offers better compression. Seean example watch file.

Remove the packagename_X.Y.Z.orig.tar.gz tarball and do

uscan --force-download

Thanks to the magic of uscan, this command will download the upstream tarball, remove the files are save it as packagename_x.y.x+dfsg.orig.tar.gz. No need to edit the ...orig.tar, remove the file and save it manually as ...+dfsg.orig.tar.gz.

Now set aside the uncommitted changes to the git repo (git stash) and import the repacked tarball:

gbp import-orig --pristine-tar ../packagename_X.Y.Z+dfsg.orig.tar.gz

Now restore the changes to debian/copyight and debian/watch (git stash apply) and edit the changelog - the version in the 1st line should read:

packagename (X.Y.Z+dfsg-1) unstable; urgency=low

Finally commit your changes with:

git commit -am 'repack to ...'

You can also see node-levn and node-loose-envify as examples.

Sources

- Based on a tip from Jérémy Lal, with contributions by Pirate Praveen, Ross Gammon and Jonas Smedegaard.

- https://pkg-perl.alioth.debian.org/howto/repacking.html

- https://wiki.debian.org/Diaspora/Packaging/origsource