From: Simon Josefsson <simon@josefsson.org>
Subject: Debian's gnulib source package

Gnulib upstream is a source-only project with no release tarballs,
versioned releases or even git tags.  Typical gnulib users is the
maintainer of some other upstream project (e.g., GNU CoreUtils) who
import files from a chosen git commit of gnulib.

As such, gnulib is a bit different from most upstream projects and,
consequently, different from most Debian packages.

Gnulib upstream provides stable branches and Git bundles:

https://www.gnu.org/software/gnulib/manual/html_node/Stable-Branches.html
https://www.gnu.org/software/gnulib/manual/html_node/Gnulib-Git-Bundle.html

We intentionally want to ship a complete git repository (with full
history) in the resulting *.deb, so the *.orig.tar.gz source package
has to contain a complete git repository as well.  We achieve this by
shipping a Git Bundle for the gnulib repository, taken from upstream.

The reason for shipping the entire git repository is that other
packages can then Build-Depends on 'gnulib' and use gnulib-tool with
GNULIB_URL=/usr/share/gnulib/gnulib.bundle and GNULIB_REVISION stored
in bootstrap.conf to pick out the particular git commit that the
relevant project was bootstrapped for.  Maintainers of projects using
gnulib pick a particular gnulib git commit, and there is no official
releases of gnulib to coordinate which commit to pick, so maintainers
usually chose the latest gnulib HEAD commit at the time they are
preparing their releases.  We could in theory prune the git repository
to only contain the particular GNULIB_REVISION commits necessary for
building other packages in Debian, but for simplicitly this package
supports all possible versions by shipping the entire git repository.

In the binary Debian package, the files in /usr/share/gnulib will
correspond to files on the stable-20XXYYZZ branch, except for
/usr/share/gnulib/gnulib.bundle which is a git bundle containing both
master and stable branches.  This approach allow /usr/share/gnulib to
be an unpacked stable gnulib release, but allows any newer commits
from the latest master branch in /usr/share/gnulib/gnulib.bundle which
is intended to be used by other packages for bootstrap builds.

The *.orig.tar.* tarball is synthesized by tag2upload from the Salsa
Git repository, and we store a copy of the GBP synthesized sources in
the pristine-tar branch for reproducible local rebuilds and to record
a GPG signature.

To update Salsa Git to the latest release the following manual process
may be used (don't proceed if any command fails):

B=stable-202607 # upstream's stable branch you want in /usr/share/gnulib
V=20260704 # upstream bundle release file
REV=491f1bb7d3049f3ab7825f3ee665c209658e9965 # gnulib git master commit
cd ~/dpkg/
git clone git@salsa.debian.org:debian/gnulib.git
cd gnulib
uscan -ddd -v # verify proper download of upstream git bundle
sha256sum ../gnulib-$V.bundle # compare to gnulib manual
git remote add gnu ../gnulib-$V.bundle
git fetch gnu
git checkout -B upstream-master gnu/master
git checkout -B upstream-stable gnu/$B
git checkout upstream-stable
cp ../gnulib-$V.bundle gnulib.bundle
git add gnulib.bundle
git commit -m "Add gnulib-$V.bundle" gnulib.bundle
git tag -m "Imported branch $B of upstream $V" -s upstream/$V
git checkout debian/latest
git merge -X theirs upstream-stable
dch -v $V-1 "New upstream (branch $B master $REV)"
git commit -m "Update changelog for $V-1 version" debian/changelog
gbp export-orig --no-pristine-tar
gpg -a -b ../gnulib_$V.orig.tar.gz
pristine-tar commit --signature-file ../gnulib_$V.orig.tar.gz.asc ../gnulib_$V.orig.tar.gz upstream-stable

Then build the package as usual, for example:

gbp buildpackage --git-pbuilder --git-pbuilder-options=--source-only-changes

Don't forget to update debian/tests/test-dh-gnulib-patch with new
branch names and commit id's for debci/autopkgtest.

Don't add anything to Build-Depends* because many low-level tools
depend on gnulib, so this could trigger a circular dependency loop.
Currently the only Build-Depends* is texinfo, and it is optional under
the 'nodoc' build profile.  We could even drop that by default, it
seems unclear if we need to ship it in Debian when it is available at
<https://www.gnu.org/software/gnulib/manual/html_node/index.html>
although some Info manuals make cross-references to the gnulib manual
and there is a lot of collected wisdom in the gnulib manual.  If ever
the 'texinfo' dependency becomes a problem we could reconsider this.

Perform testing, upload to Salsa CI, and then finalize the release:

gbp dch -R --commit
git-debpush

Finally push everything after you made the upload:

git push origin upstream-master -f
git push origin upstream-stable -f
git push origin upstream/$V
git push origin pristine-tar
git push origin debian/latest
git push origin debian/$V-1
git push origin --tags
git push origin --all

Happy hacking!
