From b10977fb79b25310c8a17f2f5f43aea8aeeb83b5 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Tue, 5 Jan 2010 17:03:32 -0800 Subject: [PATCH] Add README.source and a script to do a Git-aware merge of upstream * Add README.source explaining maintenance procedures and a debian/import-upstream script to do a Git-aware merge of a new upstream release that will allow us to cherry-pick upstream patches and do proper merges. Note that I'm not planning on re-importing the upstream 1.4.11 release using this new method, so this technique will not be effective in the master branch until upstream releases 1.4.12. (cherry picked from commit a12f6de21906ad52211a0dd0d9b923fba204b2fe) --- debian/README.source | 136 +++++++++++++++++++++++++++++++++++++++++ debian/changelog | 4 ++ debian/import-upstream | 46 ++++++++++++++ 3 files changed, 186 insertions(+) create mode 100644 debian/README.source create mode 100755 debian/import-upstream diff --git a/debian/README.source b/debian/README.source new file mode 100644 index 000000000..babae40df --- /dev/null +++ b/debian/README.source @@ -0,0 +1,136 @@ +General Maintenance + + This package is maintained in Git via the Alioth pkg-k5-afs project. + Alioth is used only for repository access control and not for any of + its other features. + + Since we often pull up many upstream fixes from the upstream stable + branch due to slow upstream release frequencies, we use Git to handle + merging and patch pullups and do not attempt to export the Git + repository state as a patch set. Accordingly, this package uses + source format 1.0, since 3.0 (quilt) doesn't offer many additional + features. + + Ideally, any changes that are not strictly Debian packaging changes + should be submitted upstream first. Upstream uses Gerrit for patch + review, which makes it very easy for anyone who wishes to submit + patches for review using Git. See: + + http://www.dementia.org/twiki/bin/view/AFSLore/GitDevelopers + + for information on how to submit patches upstream. There are some + Debian-specific patches to the upstream source in the 1.4 versions of + the Debian packages, but in the 1.5 experimental branch there are no + Debian changes outside of the debian/* directory. We want to keep it + that way if at all possible. + +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. Add "+dfsg" to the upstream version to + indicate that we are repacking the upstream release tarball. You + will need to commit this change before continuing. + + 2. Update debian/rules to change the UPSTREAM variable if obtaining + the upstream tarballs from a different location. If you do not run + AFS on the system from which you're preparing a release, you'll + also need to change this to a URL and use wget instead of cp. You + will need to commit this change before continuing. + + 3. Run debian/rules get-orig-source. This will repack the upstream + tarball, remove non-DFSG files and the WINNT directory, and create + a file named openafs_.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 + + This will be required to locate the tag for the new upstream + release. + + 5. Determine the release tag corresponding to this tarball. At the + time of this writing, upstream uses tags in the form: + + openafs-stable- + openafs-devel- + + for stable and development releases respectively. 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 + + where is the tarball created by get-orig-source above, + is the corresponding tag from the upstream Git + repository, and is of the form upstream/ where + is the non-Debian portion of the package version number. + (In other words, including any tildes and the "+dfsg" part, but not + the dash and the Debian revision.) + + 7. Merge the new upstream source into the master branch: + + git checkout master + git merge + + where is the tag you used above. You can also just + merge with the upstream branch; either is equivalent. + + 8. Flesh out the changelog entry for the new version with a summary of + what changed in that release, and continue as normal with Debian + packaging. + +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 . 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 ) + + to the changelog entry where 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: + - [] + - ... + + 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 + down. + + -- Russ Allbery <rra@debian.org>, Tue, 5 Jan 2010 16:50:11 -0800 diff --git a/debian/changelog b/debian/changelog index 8f237e5bf..0b896a96c 100644 --- a/debian/changelog +++ b/debian/changelog @@ -37,6 +37,10 @@ openafs (1.5.61+dfsg-1) UNRELEASED; urgency=low openafs-modules-source so that, should someone build a Debian source package from it, it won't have the same name as the main openafs source package. + * Add README.source explaining maintenance procedures and a + debian/import-upstream script to do a Git-aware merge of a new + upstream release that will allow us to cherry-pick upstream patches + and do proper merges. -- Russ Allbery <rra@debian.org> Fri, 21 Aug 2009 22:19:03 -0700 diff --git a/debian/import-upstream b/debian/import-upstream new file mode 100755 index 000000000..995deb72c --- /dev/null +++ b/debian/import-upstream @@ -0,0 +1,46 @@ +#!/bin/sh +# +# This script is used rather than git-import-orig to import a new upstream +# tarball. It does essentially the same work as git-import-orig -- take the +# contents of the tarball and commit it to the upstream branch and then tag it +# with a new upstream/* tag -- but it records that commit as a merge commit +# between the upstream branch and another tag. +# +# The purpose of this procedure is to have the imported tarball look to Git +# like a merge between upstream's tagged Git tree corresponding to that +# tarball and our upstream branch. This lets things like git cherry-pick work +# properly against upstream's release branch. +# +# This script assumes that the upstream tarball has already had non-DFSG +# material removed. +# +# Written by Sam Hartman <hartmans@debian.org> for krb5 +# Adopted for openafs by Russ Allbery <rra@debian.org> + +set -e + +if [ $# -ne 3 ] ; then + echo "Usage: import-upstream <tarball> <upstream-tag> <local-tag>" >&2 + exit 2 +fi +tarball="$1" +upstream="$2" +tag="$3" + +# Unpack the tarball. +dir=$(basename $(tar tzf "$tarball" | head -1)) +tar xzf "$tarball" + +# Add the tarball to the current index and then use that to create a tree +# object corresponding to the contents of that directory. Then, use +# commit-tree to commit that to the repository. +git add -f "$dir" +tree=$(git write-tree --prefix="$dir"/) +commit=$(echo "Imported upstream tag $upstream via tarball" | \ + git commit-tree "$tree" -p upstream -p $(git rev-list -n1 "$upstream")) + +# Now that we have a commit, repoint upstream at that commit, tag it, and then +# remove the unpacked upstream tarball from our index. +git branch -f upstream "$commit" +git tag "$tag" "$commit" +git rm -q -r -f "$dir" -- 2.39.5