debian/README.source

   1 Debian OpenSSH source package handling
   2 ======================================
   3
   4 The Debian package of OpenSSH is maintained in Bazaar
   5 (http://bazaar-vcs.org/, or the 'bzr' package in Debian). You will need at
   6 least version 1.16.1; the version in Debian testing as of the time of
   7 writing (2009-12-21) is fine, or you can use the version in lenny-backports.
   8 URLs are as follows:
   9
  10   Anonymous branch: http://bzr.debian.org/pkg-ssh/openssh/trunk
  11   Web browsing:     http://bzr.debian.org/loggerhead/pkg-ssh/openssh/trunk
  12   Authenticated, for developers with commit access only:
  13                     bzr+ssh://bzr.debian.org/bzr/pkg-ssh/openssh/trunk
  14
  15 Although it's possible that I may use something like bzr-loom in the future
  16 to better manage things like the Kerberos/GSSAPI patch, right now there's no
  17 funny business and all that developers need to do is:
  18
  19   # To check out:
  20   bzr co bzr+ssh://bzr.debian.org/bzr/pkg-ssh/openssh/trunk openssh
  21
  22   # To update:
  23   bzr up
  24
  25   # To edit:
  26   # hack hack hack, and 'bzr add' any new files
  27   debcommit # or bzr commit
  28   # note that this pushes automatically; you can use 'bzr unbind' to
  29   # temporarily prevent this, or 'bzr branch' to create a local branch which
  30   # you can merge later
  31
  32   # To release:
  33   dch -r && debcommit -r
  34
  35 If you have lots of branches, you'll probably want to use a shared
  36 repository to save space. Run 'bzr init-repo .' in an ancestor directory of
  37 all your OpenSSH working directories. For example, I have a shared
  38 repository in ~/src/debian/openssh/, upstream checkouts in
  39 ~/src/debian/openssh/upstream/, and my own working trees in
  40 ~/src/debian/openssh/trunk/.
  41
  42 Patch handling
  43 --------------
  44
  45 This package uses quilt to manage all modifications to the upstream source.
  46 Changes are stored in the source package as diffs in debian/patches and
  47 applied automatically by dpkg-source when the source package is extracted.
  48
  49 To configure quilt to use debian/patches instead of patches, you want either
  50 to export QUILT_PATCHES=debian/patches in your environment or use this
  51 snippet in your ~/.quiltrc:
  52
  53     for where in ./ ../ ../../ ../../../ ../../../../ ../../../../../; do
  54         if [ -e ${where}debian/rules -a -d ${where}debian/patches ]; then
  55                 export QUILT_PATCHES=debian/patches
  56                 break
  57         fi
  58     done
  59
  60 After unpacking the source package, all patches will be applied, and you can
  61 use quilt normally.
  62
  63 If you check out the source code from bzr, then all patches will be applied,
  64 but you will need to inform quilt of this manually.  Do this by running:
  65
  66     debian/rules quilt-setup
  67
  68 To add a new set of changes, first run quilt push -a, and then run:
  69
  70     quilt new <patch>
  71
  72 where <patch> is a descriptive name for the patch, used as the filename in
  73 debian/patches.  Then, for every file that will be modified by this patch,
  74 run:
  75
  76     quilt add <file>
  77
  78 before editing those files.  You must tell quilt with quilt add what files
  79 will be part of the patch before making changes or quilt will not work
  80 properly.  After editing the files, run:
  81
  82     quilt refresh
  83
  84 to save the results as a patch.
  85
  86 Alternately, if you already have an external patch and you just want to add
  87 it to the build system, run quilt push -a and then:
  88
  89     quilt import -P <patch> /path/to/patch
  90     quilt push -a
  91
  92 (add -p 0 to quilt import if needed). <patch> as above is the filename to
  93 use in debian/patches.  The last quilt push -a will apply the patch to make
  94 sure it works properly.
  95
  96 To remove an existing patch from the list of patches that will be applied,
  97 run:
  98
  99     quilt delete <patch>
 100
 101 You may need to run quilt pop -a to unapply patches first before running
 102 this command.
 103
 104 You should only commit changes to bzr with all patches applied, i.e. after
 105 'quilt push -a'.
 106
 107 Merging new upstream releases
 108 -----------------------------
 109
 110 (Most developers will not need to read this section.)
 111
 112 Thanks to the import from Portable OpenSSH CVS provided by Launchpad
 113 (https://code.launchpad.net/~vcs-imports/openssh/main, accessible by the
 114 shortcut 'lp:openssh' from the bzr client), the Debian branch is a true DVCS
 115 branch from upstream. This is a worthwhile property, but preserving it does
 116 take a little bit of work.
 117
 118 Launchpad only imports CVS HEAD, but upstream sometimes produces releases
 119 from a branch. We use the same software used by Launchpad to import the
 120 branch as well, but a few small hacks are necessary to do good branch
 121 imports. In Bazaar, it's important that the same file in different branches
 122 should have the same file-id, otherwise merge attempts will try to delete
 123 and re-add the file which usually doesn't work out very well. Occasionally a
 124 file is added to CVS HEAD and then also added to a branch, and cscvs isn't
 125 quite smart enough to spot this and copy over the file-id. We need to help
 126 it out.
 127
 128 To fetch the necessary code:
 129
 130   bzr get lp:~cjwatson/launchpad-cscvs/openssh-branch-imports
 131   # or 'bzr pull' in the appropriate directory to update this, if you
 132   # already have a copy
 133
 134 To import a branch, V_5_3 in this example:
 135
 136   export PATH="/path/to/cscvs/openssh-branch-imports:$PATH"
 137   export PYTHONPATH=/path/to/cscvs/openssh-branch-imports/modules:/path/to/cscvs/openssh-branch-imports
 138   # in a CVS checkout of :ext:anoncvs@anoncvs.mindrot.org:/cvs module
 139   # openssh:
 140   cscvs cache -b
 141   # or 'cscvs cache -u' if you've done this before and want to update
 142   cvs up -rV_5_3
 143
 144   # Now we need to get a few bits of information from cscvs' cache.
 145   sqlite CVS/Catalog.sqlite
 146   sqlite> select csnum,log from changeset where branch = 'V_5_3' order by startdate;
 147   # There will be a solid block of "Creation of branch V_5_3" changesets at
 148   # the start; look for the first revision *after* this. Substitute this in
 149   # the following wherever you see "CSX".
 150   sqlite> select revision,filename from revision where branch = 'V_5_3' and csnum >= CSX and revision not like '%.%.%' order by filename;
 151   # Anything listed here will need to be added to the openssh_ids dictionary
 152   # in modules/CVS/StorageLayer.py in cscvs. Please send Colin Watson a
 153   # patch if you do this.
 154
 155   # Next, look up the branchpoint revision in the main bzr import (bzr get
 156   # lp:openssh). It's usually easiest to just look it up by commit message
 157   # and double-check the timestamp. Substitute this revision number for
 158   # "BPR" in the following. /path/to/openssh/main is wherever you've checked
 159   # out lp:openssh.
 160   bzr get -rBPR /path/to/openssh/main /path/to/openssh/5.3
 161   # If you're using Bazaar signed commits with a GPG agent, make sure that
 162   # your agent has seen your passphrase recently. Now you can start the
 163   # actual import!
 164   cscvs -D4 totla -SC V_5_3.CSX: /path/to/openssh/5.3
 165   # If this fails at the end with a "directories differ" message, you may
 166   # have forgotten to switch your CVS checkout to the appropriate branch
 167   # with 'cvs up -r...' above. Otherwise you'll have to debug this for
 168   # yourself. It's also worth double-checking that any files added to the
 169   # branch have file-ids matching those on the trunk, using 'bzr ls -R
 170   # --show-ids'.
 171
 172 Now we have a Bazaar branch corresponding to what's in CVS. Previous such
 173 branches are available from Launchpad, for reference purposes:
 174
 175   https://code.launchpad.net/openssh
 176
 177 However, upstream releases involve a 'make distprep' step as well to
 178 construct the tarball, and we need to import the results of this as well to
 179 get a clean package.
 180
 181 Start by unpacking the upstream tarball (remember to check its GPG signature
 182 first!). Copy the .bzr directory from the upstream branch you prepared
 183 earlier. Now we have another branch, but with a working tree corresponding
 184 to the upstream tarball. Modifications and deletions are handled
 185 automatically, but we need to handle additions explicitly to make sure
 186 file-ids are correct (see above). Run:
 187
 188   bzr add --file-ids-from=/path/to/openssh/debian/trunk
 189   bzr st --show-ids
 190   # compare this with 'bzr ls --show-ids' in the Debian trunk to make sure
 191   # the result will be mergeable
 192   bzr ci -m 'Import 5.3p1 tarball'
 193
 194 Add a parent revision for the previous tarball branch, to make it easier for
 195 bzr to compute accurate merges.
 196
 197   bzr log -n0 /path/to/openssh/debian/trunk | less
 198   # find revision number for previous tarball import, hence 'PREVIOUS'
 199   bzr merge -rPREVIOUS /path/to/openssh/debian/trunk
 200   # merge history only, no file changes
 201   bzr revert .
 202   bzr ci -m 'add 5.2p1 tarball parent revision'
 203
 204 Next, merge this into the gssapi branch
 205 (bzr+ssh://bzr.debian.org/bzr/pkg-ssh/openssh/gssapi/). For this branch, we
 206 want to ignore the normal results of merging and take only the patch from
 207 http://www.sxw.org.uk/computing/patches/openssh.html; of course such a patch
 208 needs to exist first! To do this, run this in the gssapi branch:
 209
 210   bzr merge /path/to/openssh/tarball/branch
 211   bzr revert -rrevno:-1:/path/to/openssh/tarball/branch .
 212   patch -p1 </path/to/openssh/gssapi/patch
 213   bzr add --file-ids-from=/path/to/openssh/debian/trunk
 214   # you may need to deal with applying configure.ac changes to configure
 215   # here
 216   bzr ci -m 'import openssh-5.3p1-gsskex-all-20100124.patch'
 217
 218 You should now be able to 'bzr merge' from the gssapi branch into the Debian
 219 trunk, resolve conflicts, and commit. If you see lots of "Contents conflict"
 220 messages, you may have got the file-ids wrong. Once you've committed the
 221 merge, you can throw away the tarball branch, as all its history will have
 222 been incorporated.