/pkg-ssh/openssh/trunk

To get this branch, use:
bzr branch https://alioth.debian.org/scm/loggerhead/pkg-ssh/openssh/trunk
3321 by Colin Watson
Add debian/README.source with instructions on bzr handling.
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
3472 by Colin Watson
update README.source too
10
  Anonymous branch: http://anonscm.debian.org/bzr/pkg-ssh/openssh/trunk
11
  Web browsing:     http://anonscm.debian.org/loggerhead/pkg-ssh/openssh/trunk
3321 by Colin Watson
Add debian/README.source with instructions on bzr handling.
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
3376 by Colin Watson
* Update README.source to match, and add a 'quilt-setup' target to
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
3321 by Colin Watson
Add debian/README.source with instructions on bzr handling.
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
3482 by Colin Watson
bzr get -> bzr branch
130
  bzr branch lp:~cjwatson/launchpad-cscvs/openssh-branch-imports
3321 by Colin Watson
Add debian/README.source with instructions on bzr handling.
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
3482 by Colin Watson
bzr get -> bzr branch
155
  # Next, look up the branchpoint revision in the main bzr import (bzr
156
  # branch lp:openssh). It's usually easiest to just look it up by commit
157
  # message and double-check the timestamp. Substitute this revision number
158
  # for "BPR" in the following. /path/to/openssh/main is wherever you've
159
  # checked out lp:openssh.
160
  bzr branch -rBPR /path/to/openssh/main /path/to/openssh/5.3
3321 by Colin Watson
Add debian/README.source with instructions on bzr handling.
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
3322 by Colin Watson
pushed some previous upstream release branches to Launchpad
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.
3321 by Colin Watson
Add debian/README.source with instructions on bzr handling.
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
3406 by Colin Watson
handle merge history from previous tarball branch
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'
3484 by Colin Watson
actually, let's upstream-tag the revision with a tarball parent instead
203
  bzr tag upstream-5.3p1
3406 by Colin Watson
handle merge history from previous tarball branch
204
3355 by Colin Watson
describe handling of gssapi branch
205
Next, merge this into the gssapi branch
206
(bzr+ssh://bzr.debian.org/bzr/pkg-ssh/openssh/gssapi/). For this branch, we
207
want to ignore the normal results of merging and take only the patch from
208
http://www.sxw.org.uk/computing/patches/openssh.html; of course such a patch
209
needs to exist first! To do this, run this in the gssapi branch:
210
211
  bzr merge /path/to/openssh/tarball/branch
3356 by Colin Watson
fix gssapi merge instructions
212
  bzr revert -rrevno:-1:/path/to/openssh/tarball/branch .
3355 by Colin Watson
describe handling of gssapi branch
213
  patch -p1 </path/to/openssh/gssapi/patch
214
  bzr add --file-ids-from=/path/to/openssh/debian/trunk
215
  # you may need to deal with applying configure.ac changes to configure
216
  # here
217
  bzr ci -m 'import openssh-5.3p1-gsskex-all-20100124.patch'
218
219
You should now be able to 'bzr merge' from the gssapi branch into the Debian
220
trunk, resolve conflicts, and commit. If you see lots of "Contents conflict"
221
messages, you may have got the file-ids wrong. Once you've committed the
222
merge, you can throw away the tarball branch, as all its history will have
223
been incorporated.