From 148451ca0209a99eb169f56c4404c5a54d521ba4 Mon Sep 17 00:00:00 2001 From: Colin Watson Date: Mon, 21 Dec 2009 12:23:33 +0000 Subject: Add debian/README.source with instructions on bzr handling. --- debian/README.source | 129 +++++++++++++++++++++++++++++++++++++++++++++++++++ debian/changelog | 1 + 2 files changed, 130 insertions(+) create mode 100644 debian/README.source diff --git a/debian/README.source b/debian/README.source new file mode 100644 index 000000000..0ceff5996 --- /dev/null +++ b/debian/README.source @@ -0,0 +1,129 @@ +Debian OpenSSH source package handling +====================================== + +The Debian package of OpenSSH is maintained in Bazaar +(http://bazaar-vcs.org/, or the 'bzr' package in Debian). You will need at +least version 1.16.1; the version in Debian testing as of the time of +writing (2009-12-21) is fine, or you can use the version in lenny-backports. +URLs are as follows: + + Anonymous branch: http://bzr.debian.org/pkg-ssh/openssh/trunk + Web browsing: http://bzr.debian.org/loggerhead/pkg-ssh/openssh/trunk + Authenticated, for developers with commit access only: + bzr+ssh://bzr.debian.org/bzr/pkg-ssh/openssh/trunk + +Although it's possible that I may use something like bzr-loom in the future +to better manage things like the Kerberos/GSSAPI patch, right now there's no +funny business and all that developers need to do is: + + # To check out: + bzr co bzr+ssh://bzr.debian.org/bzr/pkg-ssh/openssh/trunk openssh + + # To update: + bzr up + + # To edit: + # hack hack hack, and 'bzr add' any new files + debcommit # or bzr commit + # note that this pushes automatically; you can use 'bzr unbind' to + # temporarily prevent this, or 'bzr branch' to create a local branch which + # you can merge later + + # To release: + dch -r && debcommit -r + +If you have lots of branches, you'll probably want to use a shared +repository to save space. Run 'bzr init-repo .' in an ancestor directory of +all your OpenSSH working directories. For example, I have a shared +repository in ~/src/debian/openssh/, upstream checkouts in +~/src/debian/openssh/upstream/, and my own working trees in +~/src/debian/openssh/trunk/. + +Merging new upstream releases +----------------------------- + +(Most developers will not need to read this section.) + +Thanks to the import from Portable OpenSSH CVS provided by Launchpad +(https://code.launchpad.net/~vcs-imports/openssh/main, accessible by the +shortcut 'lp:openssh' from the bzr client), the Debian branch is a true DVCS +branch from upstream. This is a worthwhile property, but preserving it does +take a little bit of work. + +Launchpad only imports CVS HEAD, but upstream sometimes produces releases +from a branch. We use the same software used by Launchpad to import the +branch as well, but a few small hacks are necessary to do good branch +imports. In Bazaar, it's important that the same file in different branches +should have the same file-id, otherwise merge attempts will try to delete +and re-add the file which usually doesn't work out very well. Occasionally a +file is added to CVS HEAD and then also added to a branch, and cscvs isn't +quite smart enough to spot this and copy over the file-id. We need to help +it out. + +To fetch the necessary code: + + bzr get lp:~cjwatson/launchpad-cscvs/openssh-branch-imports + # or 'bzr pull' in the appropriate directory to update this, if you + # already have a copy + +To import a branch, V_5_3 in this example: + + export PATH="/path/to/cscvs/openssh-branch-imports:$PATH" + export PYTHONPATH=/path/to/cscvs/openssh-branch-imports/modules:/path/to/cscvs/openssh-branch-imports + # in a CVS checkout of :ext:anoncvs@anoncvs.mindrot.org:/cvs module + # openssh: + cscvs cache -b + # or 'cscvs cache -u' if you've done this before and want to update + cvs up -rV_5_3 + + # Now we need to get a few bits of information from cscvs' cache. + sqlite CVS/Catalog.sqlite + sqlite> select csnum,log from changeset where branch = 'V_5_3' order by startdate; + # There will be a solid block of "Creation of branch V_5_3" changesets at + # the start; look for the first revision *after* this. Substitute this in + # the following wherever you see "CSX". + sqlite> select revision,filename from revision where branch = 'V_5_3' and csnum >= CSX and revision not like '%.%.%' order by filename; + # Anything listed here will need to be added to the openssh_ids dictionary + # in modules/CVS/StorageLayer.py in cscvs. Please send Colin Watson a + # patch if you do this. + + # Next, look up the branchpoint revision in the main bzr import (bzr get + # lp:openssh). It's usually easiest to just look it up by commit message + # and double-check the timestamp. Substitute this revision number for + # "BPR" in the following. /path/to/openssh/main is wherever you've checked + # out lp:openssh. + bzr get -rBPR /path/to/openssh/main /path/to/openssh/5.3 + # If you're using Bazaar signed commits with a GPG agent, make sure that + # your agent has seen your passphrase recently. Now you can start the + # actual import! + cscvs -D4 totla -SC V_5_3.CSX: /path/to/openssh/5.3 + # If this fails at the end with a "directories differ" message, you may + # have forgotten to switch your CVS checkout to the appropriate branch + # with 'cvs up -r...' above. Otherwise you'll have to debug this for + # yourself. It's also worth double-checking that any files added to the + # branch have file-ids matching those on the trunk, using 'bzr ls -R + # --show-ids'. + +Now we have a Bazaar branch corresponding to what's in CVS. However, +upstream releases involve a 'make distprep' step as well to construct the +tarball, and we need to import the results of this as well to get a clean +package. + +Start by unpacking the upstream tarball (remember to check its GPG signature +first!). Copy the .bzr directory from the upstream branch you prepared +earlier. Now we have another branch, but with a working tree corresponding +to the upstream tarball. Modifications and deletions are handled +automatically, but we need to handle additions explicitly to make sure +file-ids are correct (see above). Run: + + bzr add --file-ids-from=/path/to/openssh/debian/trunk + bzr st --show-ids + # compare this with 'bzr ls --show-ids' in the Debian trunk to make sure + # the result will be mergeable + bzr ci -m 'Import 5.3p1 tarball' + +You should now be able to 'bzr merge' from the tarball branch, resolve +conflicts, and commit. If you see lots of "Contents conflict" messages, you +may have got the file-ids wrong. Once you've committed the merge, you can +throw away the tarball branch, as all its history will have been +incorporated. diff --git a/debian/changelog b/debian/changelog index 7d2606e8c..eaab6b72b 100644 --- a/debian/changelog +++ b/debian/changelog @@ -2,6 +2,7 @@ openssh (1:5.1p1-9) UNRELEASED; urgency=low * Use x11.pc when compiling/linking gnome-ssh-askpass2 (closes: #555951). * Moved to bzr.debian.org; add Vcs-Bzr and Vcs-Browser control fields. + * Add debian/README.source with instructions on bzr handling. -- Colin Watson Thu, 12 Nov 2009 21:31:44 +0000 -- cgit v1.2.3