Add debian/README.source with instructions on bzr handling.

2 files changed, 130 insertions, 0 deletions

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 <cjwatson@debian.org>  Thu, 12 Nov 2009 21:31:44 +0000