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