c01610ed07bb98e43130f93a287a31ee1db16806
[openafs.git] / src / packaging / 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.  Accordingly, this package uses
11     source format 1.0, since 3.0 (quilt) doesn't offer many additional
12     features.
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.  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.
26
27 Importing a New Upstream Release
28
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.
35
36     Follow the following procedure to import a new upstream release:
37
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
41        will sort property.
42
43     2. Double-check the TAG setting in debian/rules to be sure it's going
44        to retrieve the correct Git tag.
45
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.
50
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:
54
55            git remote add openafs git://git.openafs.org/openafs.git
56            git fetch openafs
57
58        This will be required to locate the tag for the new upstream
59        release.
60
61     5. Determine the release tag corresponding to this tarball.  At the
62        time of this writing, upstream uses tags in the form:
63
64            openafs-stable-<version>
65            openafs-devel-<version>
66
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.
70
71     6. Import the upstream source from the tarball with:
72
73            debian/import-upstream <tarball> <upstream-tag> <local-tag>
74
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
80        Debian revision.)
81
82     7. Commit the tarball to the repository with pristine-tar, using the
83        new local tag as the reference:
84
85            pristine-tar commit <tarball> <local-tag>
86
87     8. Merge the new upstream source into the master branch:
88
89            git checkout master
90            git merge <local-tag>
91
92        where <local-tag> is the tag you used above.  You can also just
93        merge with the upstream branch; either is equivalent.
94
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
97        packaging.
98
99 Pulling Upstream Changes
100
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.
106
107     The procedure is therefore:
108
109     1. Identify the hash of the commit that you want to pull up using git
110        log or other information.
111
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:
116
117            (cherry picked from commit <hash>)
118
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.
123
124     3. Add a changelog entry and commit it separately.  Use the following
125        convention for changelog entries for cherry-picks:
126
127            * Apply upstream deltas:
128              - [<hash>] <title>
129              - ...
130
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
134        down.
135
136  -- Russ Allbery <rra@debian.org>, Tue, 13 Jul 2010 19:30:15 -0700