Re: Git and tarballs
Wolodja Wentland <firstname.lastname@example.org> writes:
> I've recently started to work on some packages and am not sure if I
> follow best practices when packaging software from git repositories with
I do the following for OpenAFS (see the supporting scripts in the openafs
source package) based on work done by Sam Hartman for krb5, and I'm very
happy with it. I'm probably going to eventually adopt the same approach
for all other software with a Git upstream.
The key feature is that the import-upstream script imports the tarball
contents but commits it as a merge between the upstream tag and the local
upstream branch, which preserves all of upstream's commit history while
simultaneously including in the upstream branch any tarball-generated
files that aren't in Git. This isn't required for OpenAFS, but for some
other packages I want to use some of the files that are generated as part
of the upstream tarball release but aren't checked in.
(This is part of debian/README.source for the openafs package.)
Importing a New Upstream Release
We want to be able to use Git to cherry-pick fixes from upstream, but
we want to base the Debian packages on the upstream tarball releases.
We also need to strip some non-DFSG files from the upstream tarball
releases and imported code, and want to drop the WINNT directory to
save some space. This means we follow a slightly complicated method
for importing a new upstream release.
Follow the following procedure to import a new upstream release:
1. Update the package version in debian/changelog to match the new
upstream version. If the new upstream version is a release
candidate, don't forget to add "~" before "rc" so that the versions
will sort property.
2. Double-check the TAG setting in debian/rules to be sure it's going
to retrieve the correct Git tag.
3. Run debian/rules get-orig-source. This will generate a tarball
from the upstream Git tag using git archive, remove the WINNT
directory, and create a file named openafs_<version>.orig.tar.gz in
the current directory.
4. Ensure that you have the OpenAFS upstream Git repository available
as a remote in the Git repository where you're doing the packaging
work and it's up to date:
git remote add openafs git://git.openafs.org/openafs.git
git fetch openafs
This will be required to locate the tag for the new upstream
5. Determine the release tag corresponding to this tarball. At the
time of this writing, upstream uses tags in the form:
for stable and development releases respectively. <version> is the
version number with periods replaced by underscores. This
convention may change, so double-check with git tag.
6. Import the upstream source from the tarball with:
debian/import-upstream <tarball> <upstream-tag> <local-tag>
where <tarball> is the tarball created by get-orig-source above,
<upstream-tag> is the corresponding tag from the upstream Git
repository, and <local-tag> is of the form upstream/<version> where
<version> is the non-Debian portion of the package version number.
(In other words, including any tildes, but not the dash and the
7. Commit the tarball to the repository with pristine-tar, using the
new local tag as the reference:
pristine-tar commit <tarball> <local-tag>
8. Merge the new upstream source into the master branch:
git checkout master
git merge <local-tag>
where <local-tag> is the tag you used above. You can also just
merge with the upstream branch; either is equivalent.
9. Flesh out the changelog entry for the new version with a summary of
what changed in that release, and continue as normal with Debian
Pulling Upstream Changes
Upstream releases, particularly stable releases, are relatively
infrequent, so it's often desirable to pull upstream changes from the
stable branch into the Debian package. This should always be done
using git cherry-pick -x so that we can use git cherry to see which
changes on the stable branch have not been picked up.
The procedure is therefore:
1. Identify the hash of the commit that you want to pull up using git
log or other information.
2. git cherry-pick -x <hash>. If the cherry-pick fails and you have
to manually do a merge, follow the instructions to use -c to keep
the original commit message as a starting point, but *also*
manually add a line like:
(cherry picked from commit <hash>)
to the changelog entry where <hash> is the full hash of the
upstream commit. Note that the upstream commits on the stable
branch will generally already have a line like this from upstream's
cherry-pick. This will be a second line.
3. Add a changelog entry and commit it separately. Use the following
convention for changelog entries for cherry-picks:
* Apply upstream deltas:
- [<hash>] <title>
where <hash> is the first eight characters of the upstream commit
hash and <title> is the first line of the upstream commit message,
edited as necessary to keep the length of the changelog lines
Russ Allbery (email@example.com) <http://www.eyrie.org/~eagle/>