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://www.dementia.org/twiki/bin/view/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.  Add "+dfsg" to the upstream version to
  42        indicate that we are repacking the upstream release tarball.  You
  43        will need to commit this change before continuing.
  44
  45     2. Update debian/rules to change the UPSTREAM variable if obtaining
  46        the upstream tarballs from a different location.  If you do not run
  47        AFS on the system from which you're preparing a release, you'll
  48        also need to change this to a URL and use wget instead of cp.  You
  49        will need to commit this change before continuing.
  50
  51     3. Run debian/rules get-orig-source.  This will repack the upstream
  52        tarball, remove non-DFSG files and the WINNT directory, and create
  53        a file named openafs_<version>.orig.tar.gz in the current
  54        directory.
  55
  56     4. Ensure that you have the OpenAFS upstream Git repository available
  57        as a remote in the Git repository where you're doing the packaging
  58        work and it's up to date:
  59
  60            git remote add openafs git://git.openafs.org/openafs.git
  61            git fetch openafs
  62
  63        This will be required to locate the tag for the new upstream
  64        release.
  65
  66     5. Determine the release tag corresponding to this tarball.  At the
  67        time of this writing, upstream uses tags in the form:
  68
  69            openafs-stable-<version>
  70            openafs-devel-<version>
  71
  72        for stable and development releases respectively.  <version> is the
  73        version number with periods replaced by underscores.  This
  74        convention may change, so double-check with git tag.
  75
  76     6. Import the upstream source from the tarball with:
  77
  78            debian/import-upstream <tarball> <upstream-tag> <local-tag>
  79
  80        where <tarball> is the tarball created by get-orig-source above,
  81        <upstream-tag> is the corresponding tag from the upstream Git
  82        repository, and <local-tag> is of the form upstream/<version> where
  83        <version> is the non-Debian portion of the package version number.
  84        (In other words, including any tildes and the "+dfsg" part, but not
  85        the dash and the Debian revision.)
  86
  87     7. Commit the tarball to the repository with pristine-tar, using the
  88        new local tag as the reference:
  89
  90            pristine-tar commit <tarball> <local-tag>
  91
  92     8. Merge the new upstream source into the master branch:
  93
  94            git checkout master
  95            git merge <local-tag>
  96
  97        where <local-tag> is the tag you used above.  You can also just
  98        merge with the upstream branch; either is equivalent.
  99
 100     9. Flesh out the changelog entry for the new version with a summary of
 101        what changed in that release, and continue as normal with Debian
 102        packaging.
 103
 104 Pulling Upstream Changes
 105
 106     Upstream releases, particularly stable releases, are relatively
 107     infrequent, so it's often desirable to pull upstream changes from the
 108     stable branch into the Debian package.  This should always be done
 109     using git cherry-pick -x so that we can use git cherry to see which
 110     changes on the stable branch have not been picked up.
 111
 112     The procedure is therefore:
 113
 114     1. Identify the hash of the commit that you want to pull up using git
 115        log or other information.
 116
 117     2. git cherry-pick -x <hash>.  If the cherry-pick fails and you have
 118        to manually do a merge, follow the instructions to use -c to keep
 119        the original commit message as a starting point, but *also*
 120        manually add a line like:
 121
 122            (cherry picked from commit <hash>)
 123
 124        to the changelog entry where <hash> is the full hash of the
 125        upstream commit.  Note that the upstream commits on the stable
 126        branch will generally already have a line like this from upstream's
 127        cherry-pick.  This will be a second line.
 128
 129     3. Add a changelog entry and commit it separately.  Use the following
 130        convention for changelog entries for cherry-picks:
 131
 132            * Apply upstream deltas:
 133              - [<hash>] <title>
 134              - ...
 135
 136        where <hash> is the first eight characters of the upstream commit
 137        hash and <title> is the first line of the upstream commit message,
 138        edited as necessary to keep the length of the changelog lines
 139        down.
 140
 141  -- Russ Allbery <rra@debian.org>, Tue, 19 Jan 2010 20:34:36 -0800