--- /dev/null
+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_<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
+
+ 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-<version>
+ openafs-devel-<version>
+
+ 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 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 <local-tag>
+
+ where <local-tag> 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 <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
+ down.
+
+ -- Russ Allbery <rra@debian.org>, Tue, 5 Jan 2010 16:50:11 -0800
--- /dev/null
+#!/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"
projects / packages / o / openafs.git / commitdiff