179fe1b0a38e39b3261ab8fe8b2c3e5a99925755
[pkg-k5-afs/openafs.git] / debian / README.source
1 General Maintenance
2
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
5     its other features.
6
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.  This package uses 3.0 (quilt) but
11     configures it to use a single debian patch that includes all the
12     merged changes.
13
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:
18
19         http://wiki.openafs.org/AFSLore/GitDevelopers
20
21     for information on how to submit patches upstream.  Starting from
22     OpenAFS 1.5, we're no longer carrying any substantial Debian-specific
23     changes outside of the debian/* directory, only temporary bug
24     workarounds, and we want to keep it that way.
25
26 Importing a New Upstream Release
27
28     We want to be able to use Git to cherry-pick fixes from upstream, but
29     we want to base the Debian packages on the upstream tarball releases.
30     We also need to strip some non-DFSG files from the upstream tarball
31     releases and imported code, and want to drop the WINNT directory to
32     save some space.  This means we follow a slightly complicated method
33     for importing a new upstream release.
34
35     Follow the following procedure to import a new upstream release:
36
37     1. Update the package version in debian/changelog to match the new
38        upstream version.  If the new upstream version is a release
39        candidate, don't forget to add "~" before "rc" so that the versions
40        will sort property.
41
42     2. Double-check the TAG setting in debian/rules to be sure it's going
43        to retrieve the correct Git tag.
44
45     3. Run debian/rules get-orig-source.  This will generate a tarball
46        from the upstream Git tag using git archive, remove the WINNT
47        directory, and create a file named openafs_<version>.orig.tar.xz in
48        the current directory.
49
50     4. Ensure that you have the OpenAFS upstream Git repository available
51        as a remote in the Git repository where you're doing the packaging
52        work and it's up to date:
53
54            git remote add openafs git://git.openafs.org/openafs.git
55            git fetch openafs
56
57        This will be required to locate the tag for the new upstream
58        release.
59
60     5. Determine the release tag corresponding to this tarball.  At the
61        time of this writing, upstream uses tags in the form:
62
63            openafs-stable-<version>
64            openafs-devel-<version>
65
66        for stable and development releases respectively.  <version> is the
67        version number with periods replaced by underscores.  This
68        convention may change, so double-check with git tag.
69
70     6. Import the upstream source from the tarball with:
71
72            gbp import-orig --upstream-vcs-tag <tag> <tarball>
73
74        where <tarball> is the tarball created by get-orig-source above and
75        <tag> is the corresponding tag from the upstream Git repository.
76
77     7. Flesh out the changelog entry for the new version with a summary of
78        what changed in that release, and continue as normal with Debian
79        packaging.
80
81 Pulling Upstream Changes
82
83     Upstream releases, particularly stable releases, are relatively
84     infrequent, so it's often desirable to pull upstream changes from the
85     stable branch into the Debian package.  This should always be done
86     using git cherry-pick -x so that we can use git cherry to see which
87     changes on the stable branch have not been picked up.
88
89     The procedure is therefore:
90
91     1. Identify the hash of the commit that you want to pull up using git
92        log or other information.
93
94     2. git cherry-pick -x <hash>.  If the cherry-pick fails and you have
95        to manually do a merge, follow the instructions to use -c to keep
96        the original commit message as a starting point, but *also*
97        manually add a line like:
98
99            (cherry picked from commit <hash>)
100
101        to the changelog entry where <hash> is the full hash of the
102        upstream commit.  Note that the upstream commits on the stable
103        branch will generally already have a line like this from upstream's
104        cherry-pick.  This will be a second line.
105
106     3. Add a changelog entry and commit it separately.  Use the following
107        convention for changelog entries for cherry-picks:
108
109            * Apply upstream deltas:
110              - [<hash>] <title>
111              - ...
112
113        where <hash> is the first eight characters of the upstream commit
114        hash and <title> is the first line of the upstream commit message,
115        edited as necessary to keep the length of the changelog lines
116        down.
117
118  -- Russ Allbery <rra@debian.org>, Sun, 20 Oct 2013 08:59:17 -0700