3 This package is maintained in Git via the Alioth pkg-k5-afs project.
4 Alioth is used only for repository access control and not for any of
7 Since we often pull up many upstream fixes from the upstream stable
8 branch due to slow upstream release frequencies, we use Git to handle
9 merging and patch pullups and do not attempt to export the Git
10 repository state as a patch set. Accordingly, this package uses
11 source format 1.0, since 3.0 (quilt) doesn't offer many additional
14 Ideally, any changes that are not strictly Debian packaging changes
15 should be submitted upstream first. Upstream uses Gerrit for patch
16 review, which makes it very easy for anyone who wishes to submit
17 patches for review using Git. See:
19 http://wiki.openafs.org/AFSLore/GitDevelopers/
21 for information on how to submit patches upstream. There are some
22 Debian-specific patches to the upstream source in the 1.4 versions of
23 the Debian packages, but in the 1.5 experimental branch there are no
24 Debian changes outside of the debian/* directory. We want to keep it
25 that way if at all possible.
27 Importing a New Upstream Release
29 We want to be able to use Git to cherry-pick fixes from upstream, but
30 we want to base the Debian packages on the upstream tarball releases.
31 We also need to strip some non-DFSG files from the upstream tarball
32 releases and imported code, and want to drop the WINNT directory to
33 save some space. This means we follow a slightly complicated method
34 for importing a new upstream release.
36 Follow the following procedure to import a new upstream release:
38 1. Update the package version in debian/changelog to match the new
39 upstream version. If the new upstream version is a release
40 candidate, don't forget to add "~" before "rc" so that the versions
43 2. Double-check the TAG setting in debian/rules to be sure it's going
44 to retrieve the correct Git tag.
46 3. Run debian/rules get-orig-source. This will generate a tarball
47 from the upstream Git tag using git archive, remove the WINNT
48 directory, and create a file named openafs_<version>.orig.tar.gz in
49 the current directory.
51 4. Ensure that you have the OpenAFS upstream Git repository available
52 as a remote in the Git repository where you're doing the packaging
53 work and it's up to date:
55 git remote add openafs git://git.openafs.org/openafs.git
58 This will be required to locate the tag for the new upstream
61 5. Determine the release tag corresponding to this tarball. At the
62 time of this writing, upstream uses tags in the form:
64 openafs-stable-<version>
65 openafs-devel-<version>
67 for stable and development releases respectively. <version> is the
68 version number with periods replaced by underscores. This
69 convention may change, so double-check with git tag.
71 6. Import the upstream source from the tarball with:
73 debian/import-upstream <tarball> <upstream-tag> <local-tag>
75 where <tarball> is the tarball created by get-orig-source above,
76 <upstream-tag> is the corresponding tag from the upstream Git
77 repository, and <local-tag> is of the form upstream/<version> where
78 <version> is the non-Debian portion of the package version number.
79 (In other words, including any tildes, but not the dash and the
82 7. Commit the tarball to the repository with pristine-tar, using the
83 new local tag as the reference:
85 pristine-tar commit <tarball> <local-tag>
87 8. Merge the new upstream source into the master branch:
92 where <local-tag> is the tag you used above. You can also just
93 merge with the upstream branch; either is equivalent.
95 9. Flesh out the changelog entry for the new version with a summary of
96 what changed in that release, and continue as normal with Debian
99 Pulling Upstream Changes
101 Upstream releases, particularly stable releases, are relatively
102 infrequent, so it's often desirable to pull upstream changes from the
103 stable branch into the Debian package. This should always be done
104 using git cherry-pick -x so that we can use git cherry to see which
105 changes on the stable branch have not been picked up.
107 The procedure is therefore:
109 1. Identify the hash of the commit that you want to pull up using git
110 log or other information.
112 2. git cherry-pick -x <hash>. If the cherry-pick fails and you have
113 to manually do a merge, follow the instructions to use -c to keep
114 the original commit message as a starting point, but *also*
115 manually add a line like:
117 (cherry picked from commit <hash>)
119 to the changelog entry where <hash> is the full hash of the
120 upstream commit. Note that the upstream commits on the stable
121 branch will generally already have a line like this from upstream's
122 cherry-pick. This will be a second line.
124 3. Add a changelog entry and commit it separately. Use the following
125 convention for changelog entries for cherry-picks:
127 * Apply upstream deltas:
131 where <hash> is the first eight characters of the upstream commit
132 hash and <title> is the first line of the upstream commit message,
133 edited as necessary to keep the length of the changelog lines
136 -- Russ Allbery <rra@debian.org>, Tue, 13 Jul 2010 19:30:15 -0700