Merge lp:~jr/ubuntu-packaging-guide/fixes into lp:ubuntu-packaging-guide
- fixes
- Merge into trunk
Status: | Merged |
---|---|
Approved by: | Barry Warsaw |
Approved revision: | 61 |
Merged at revision: | 42 |
Proposed branch: | lp:~jr/ubuntu-packaging-guide/fixes |
Merge into: | lp:ubuntu-packaging-guide |
Diff against target: |
900 lines (+182/-227) 13 files modified
debian-dir-overview.rst (+13/-7) fixing-a-bug.rst (+9/-20) getting-set-up.rst (+24/-18) index.rst (+22/-4) introduction-to-ubuntu-development.rst (+5/-5) knowledge-base.rst (+0/-27) udd-intro.rst (+35/-58) udd-latest.rst (+2/-2) udd-merging.rst (+9/-10) udd-patchsys.rst (+9/-10) udd-sponsorship.rst (+9/-9) udd-uploading.rst (+28/-25) udd-working.rst (+17/-32) |
To merge this branch: | bzr merge lp:~jr/ubuntu-packaging-guide/fixes |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Barry Warsaw (community) | Approve | ||
Daniel Holbach (community) | Needs Information | ||
Review via email: mp+67951@code.launchpad.net |
Commit message
Description of the change
A bunch of fixes to tidy up parts of the packaging guide
Jonathan Riddell (jr) wrote : | # |
- Why do you remove the section about libvigraimpex?
- the section following "Then determine the source package corresponding to this binary package::" seems to have been correct before.
apt-cache show <package> gives different results if the binary package has the same or a different name than the source package. So I replaced it with apt-cache showsrc <package> which acts the same in both cases, so the libvigraimpex case is no longer needed.
- bzr commit instead of debcommit? (debcommit does much more than just 'bzr commit')
From bzr 2.4 and bzr-builddeb 2.7.5 bzr commit now magically takes the commit message from debian/changelog too, the feeling among UDD developers is it's better to use bzr commands to keep things consistent.
- Do you think it makes sense to have two copies of the knowledge base article index?
No, I'll remove that
- Why do you leave the link to intrepid and remove the link to natty? (line 419)
Intrepid is used in the doc as an example of a past release. I removed references to Natty as an example of a current development release because it's confusing since it not a current development release.
I don't think the links to release wiki pages are very important either way.
- Is "bzr tag" necessary nowadays?
Yes it tags with the current release version. bzr mark-uploaded is now no longer needed.
- Why do you remove the "update-maintainer" bits?
As agreed with barry this isn't a good place to include it, I'll file a bug to add it back elsewhere such as the debian/ directory introduction page.
- 61. By Jonathan Riddell
-
remove duplicate knowledge base index
Barry Warsaw (barry) wrote : | # |
On the libvigraimpex thing, I think you should show two examples, one where the source and binary package names are the same, and one where they're different, e.g.
$ apt-cache showsrc tomboy | grep ^Package:
Package: tomboy
$ apt-cache showsrc python-vigra | grep ^Package:
Package: libvigraimpex
BTW, there's also now a packaging-dev package which gets you most (but I think not all, e.g. cdbs) packages you'll need to do basic package management. We should recommend people install that if we don't already.
s/every day CD images/every day, CD images/
Are you sure this recommendation will always work:
$ bzr log ubuntu:sysvinit | grep ^tags | head -n 1
IOW no possibility of subsequent tags confusing things, even in the face of user error?
Everything else looks good to me. I think you can merge once those changes are made.
Morten Kjeldgaard (mok0) wrote : | # |
> - Why do you leave the link to intrepid and remove the link to
> natty? (line 419)
>
> Intrepid is used in the doc as an example of a past release. I
> removed references to Natty as an example of a current development
> release because it's confusing since it not a current development
> release.
For documentation purposes such as this it would actually be useful if
Ubuntu releases had a constant code name during the development phase
(like Debians "Sid")... for example "Developing Dodo" :-)
-- Morten
Daniel Holbach (dholbach) wrote : | # |
Could it be that a result of this merge there's a couple of warnings now?
daniel@
sphinx-build -b html -d _build/doctrees . _build/html
Making output directory...
Running Sphinx v1.1pre
loading pickled environment... not yet created
building [html]: targets for 15 source files that are out of date
updating environment: 15 added, 0 changed, 0 removed
reading sources... [100%] udd-working
/home/daniel/
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] udd-working
/home/daniel/
/home/daniel/
writing additional files... genindex search
copying images... [100%] images/
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 3 warnings.
Build finished. The HTML pages are in _build/html.
daniel@
Shall I file a bug?
Jonathan Riddell (jr) wrote : | # |
index.rst warning fixed
I also fixed the incorrect link in the unrelated fixing-
I've no idea how to fix the indentation in the fixing-
Daniel Holbach (dholbach) wrote : | # |
After a paragraph ending with "::" (indicating a following paragraph in preformatted text), it needs a newline. I fixed that bit in fixing-
daniel@
sphinx-build -b html -d _build/doctrees . _build/html
Making output directory...
Running Sphinx v1.1pre
loading pickled environment... not yet created
building [html]: targets for 15 source files that are out of date
updating environment: 15 added, 0 changed, 0 removed
reading sources... [100%] udd-working
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] udd-working
writing additional files... genindex search
copying images... [100%] images/
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.
Build finished. The HTML pages are in _build/html.
daniel@
Preview Diff
1 | === modified file 'debian-dir-overview.rst' |
2 | --- debian-dir-overview.rst 2011-06-01 08:05:03 +0000 |
3 | +++ debian-dir-overview.rst 2011-07-15 09:23:07 +0000 |
4 | @@ -59,7 +59,7 @@ |
5 | number) appended to the end of the Debian version. So if the Debian hello |
6 | ``2.6-1`` package was changed by Ubuntu, the version string would be |
7 | ``2.6-1ubuntu1``. If a package for the application does not exist in Debian, |
8 | -then the Debian revision is ``0`` (e.g., ``2.6-0ubuntu1``). |
9 | +then the Debian revision is ``0`` (e.g. ``2.6-0ubuntu1``). |
10 | |
11 | For further information, see the `changelog section (Section 4.4) |
12 | <http://www.debian.org/doc/debian-policy/ch-source.html#s-dpkgchangelog>`_ of |
13 | @@ -115,7 +115,7 @@ |
14 | Maintainer Field spec <https://wiki.ubuntu.com/DebianMaintainerField>`_ on the |
15 | Ubuntu wiki. |
16 | |
17 | -Each additional paragraph describes a binary package built. |
18 | +Each additional paragraph describes a binary package to be built. |
19 | |
20 | For further information, see the `control file section (Chapter 5) |
21 | <http://www.debian.org/doc/debian-policy/ch-controlfields.html>`_ of the Debian |
22 | @@ -264,10 +264,12 @@ |
23 | foo usr/bin |
24 | debian/bar.desktop usr/share/applications |
25 | |
26 | -In the second case, files installed into ``debian/tmp`` can then be moved into |
27 | -separate binary packages using multiple ``$package_name.install`` files. This |
28 | -is often done to split large amounts of architecture independent data out of |
29 | -architecture dependent packages and into ``Architecture: all`` packages. In |
30 | +When a source package is producing multiple binary packages ``dh`` will |
31 | +install the files into ``debian/tmp`` rather than directly into |
32 | +``debian/<package>``. Files installed into ``debian/tmp`` can then be moved |
33 | +into separate binary packages using multiple ``$package_name.install`` files. |
34 | +This is often done to split large amounts of architecture independent data out |
35 | +of architecture dependent packages and into ``Architecture: all`` packages. In |
36 | this case, only the name of the files (or directories) to be installed are |
37 | needed without the installation directory. For example, ``foo.install`` |
38 | containing only the architecture dependent files might look like:: |
39 | @@ -319,6 +321,10 @@ |
40 | 4.11) <http://www.debian.org/doc/debian-policy/ch-source.html#s-debianwatch>`_ |
41 | of the Debian Policy Manual. |
42 | |
43 | +For a list of packages where the ``watch`` file reports they are not in sync |
44 | +with upstream see `Ubuntu External Health Status |
45 | +<http://qa.ubuntuwire.org/uehs/no_updated.html>`_. |
46 | + |
47 | The source/format file |
48 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
49 | |
50 | @@ -327,7 +333,7 @@ |
51 | to use the newer 3.0 source format. In this case, the file should contain a |
52 | single line indicating the desired format: |
53 | |
54 | -* ``3.0 (native)`` for Debian native packages or |
55 | +* ``3.0 (native)`` for Debian native packages (no upstream version) or |
56 | |
57 | * ``3.0 (quilt)`` for packages with a separate upstream tarball |
58 | |
59 | |
60 | === modified file 'fixing-a-bug.rst' |
61 | --- fixing-a-bug.rst 2011-06-03 21:23:43 +0000 |
62 | +++ fixing-a-bug.rst 2011-07-15 09:23:07 +0000 |
63 | @@ -19,7 +19,7 @@ |
64 | Finding the problem |
65 | =================== |
66 | |
67 | -There is a lot of different ways to find things to work on. It might be a bug |
68 | +There are a lot of different ways to find things to work on. It might be a bug |
69 | report you are encountering yourself (which gives you a good opportunity to |
70 | test the fix), or a problem you noted elsewhere, maybe in a bug report. |
71 | |
72 | @@ -55,28 +55,16 @@ |
73 | different binary packages. To find the source package for a particular binary |
74 | package, type:: |
75 | |
76 | - $ apt-cache show tomboy | grep ^Source: |
77 | - |
78 | -In this case, nothing is printed, meaning that ``tomboy`` is also the name of |
79 | -the binary package. An example where the source and binary package names |
80 | -differ is ``python-vigra``. While that is the binary package name, the source |
81 | -package is actually ``libvigraimpex`` and can be found with this command (and |
82 | -its output):: |
83 | - |
84 | - $ apt-cache show python-vigra | grep ^Source: |
85 | - Source: libvigraimpex |
86 | - |
87 | -.. XXX: Link to SRU article. |
88 | - |
89 | + $ apt-cache showsrc tomboy | grep ^Package: |
90 | |
91 | Getting the code |
92 | ================ |
93 | |
94 | Once you know the source package to work on, you will want to get a copy of |
95 | -the code on your system, so that you can debug it. This is done by |
96 | -:ref:`*branching* the source package <branching>` branch corresponding to the |
97 | -source package. Launchpad maintains source package branches for all the |
98 | -packages in Ubuntu. |
99 | +the code on your system, so that you can debug it. In Ubuntu Distributed |
100 | +Development this is done by :ref:`*branching* the source package <branching>` |
101 | +branch corresponding to the source package. Launchpad maintains source package |
102 | +branches for all the packages in Ubuntu. |
103 | |
104 | Once you've got a local branch of the source package, you can investigate the |
105 | bug, create a fix, and upload your proposed fix to Launchpad, in the form of a |
106 | @@ -84,7 +72,7 @@ |
107 | *merge proposal* <merge-proposal>`, which asks other Ubuntu developers to |
108 | review and approve your change. If they agree with your changes, an Ubuntu |
109 | developer will upload the new version of the package to Ubuntu so that |
110 | -everyone gets the benefit or your excellent fix - and you get a little bit of |
111 | +everyone gets the benefit of your excellent fix - and you get a little bit of |
112 | credit. You're now on your way to becoming an Ubuntu developer! |
113 | |
114 | We'll describe specifics on how to branch the code, push your fix, and request |
115 | @@ -182,7 +170,7 @@ |
116 | |
117 | With the changelog entry written and saved, you can just run:: |
118 | |
119 | - debcommit |
120 | + bzr commit |
121 | |
122 | and the change will be committed (locally) with your changelog entry as a |
123 | commit message. |
124 | @@ -206,3 +194,4 @@ |
125 | browser. There find the "(+) Propose for merging" link, click it to get the |
126 | change reviewed by somebody and included in Ubuntu. |
127 | |
128 | +.. XXX: Link to SRU article. |
129 | |
130 | === modified file 'getting-set-up.rst' |
131 | --- getting-set-up.rst 2011-07-12 16:11:03 +0000 |
132 | +++ getting-set-up.rst 2011-07-15 09:23:07 +0000 |
133 | @@ -4,8 +4,8 @@ |
134 | |
135 | There are a number of things you need to do to get started developing for Ubuntu. |
136 | This article is designed to get your computer set up so that you can start |
137 | -working with packages, and upload your packages to Launchpad. Here's what we'll |
138 | -cover: |
139 | +working with packages, and upload your packages to Ubuntu's hosting |
140 | +platform, Launchpad. Here's what we'll cover: |
141 | |
142 | * Installing packaging-related software. This includes: |
143 | |
144 | @@ -33,7 +33,7 @@ |
145 | |
146 | There are a number of tools that will make your life as an Ubuntu developer |
147 | much easier. You will encounter these tools later in this guide. To install |
148 | -most of the tools you will need, run this command:: |
149 | +most of the tools you will need run this command:: |
150 | |
151 | $ sudo apt-get install gnupg pbuilder ubuntu-dev-tools bzr-builddeb apt-file |
152 | |
153 | @@ -55,8 +55,9 @@ |
154 | * ``ubuntu-dev-tools`` (and ``devscripts``, a direct dependency) -- a |
155 | collection of tools that make many packaging tasks easier. |
156 | * ``bzr-builddeb`` (and ``bzr``, a dependency) -- distributed version control |
157 | - tools that makes it easy for many developers to collaborate and work on the |
158 | - same code while keeping it trivial to merge each others work. |
159 | + with Bazaar, a new way of working with packages for Ubuntu that will make it |
160 | + easy for many developers to collaborate and work on the same code while |
161 | + keeping it trivial to merge each others work. |
162 | * ``apt-file`` provides an easy way to find the binary package that contains a |
163 | given file. |
164 | * ``apt-cache`` (part of the ``apt`` package) provides even more information |
165 | @@ -84,12 +85,13 @@ |
166 | which means the key will never expire. The last questions will be about your |
167 | name and email address. Just pick the ones you are going to use for Ubuntu |
168 | development here, you can add additional email addresses later on. Adding a |
169 | -comment is not necessary. Then you will have to set a passphrase. Choose a |
170 | -safe one. |
171 | +comment is not necessary. Then you will have to set a passphrase, choose a |
172 | +safe one (a passphrase is just a password which is allowed to include spaces). |
173 | |
174 | Now GPG will create a key for you, which can take a little bit of time; it |
175 | needs random bytes, so if you give the system some work to do it will be |
176 | -just fine. Move the cursor around! |
177 | +just fine. Move the cursor around, type some paragraphs of random text, load |
178 | +some web page. |
179 | |
180 | Once this is done, you will get a message similar to this one:: |
181 | |
182 | @@ -107,8 +109,8 @@ |
183 | |
184 | This will send your key to one keyserver, but a network of keyservers will |
185 | automatically sync the key between themselves. Once this syncing is complete, |
186 | -your signed public key will be ready to verify your your contributions |
187 | -around the world. |
188 | +your signed public key will be ready to verify your contributions around the |
189 | +world. |
190 | |
191 | |
192 | Create your SSH key |
193 | @@ -117,10 +119,10 @@ |
194 | SSH_ stands for *Secure Shell*, and it is a protocol that allows you to |
195 | exchange data in a secure way over a network. It is common to use SSH to access |
196 | and open a shell on another computer, and to use it to securely transfer files. |
197 | -For our purposes, we will mainly be using SSH to securely communicate with |
198 | -Launchpad. |
199 | +For our purposes, we will mainly be using SSH to securely upload source packages |
200 | +to Launchpad. |
201 | |
202 | -To generate a SSH key, enter:: |
203 | +To generate an SSH key, enter:: |
204 | |
205 | $ ssh-keygen -t rsa |
206 | |
207 | @@ -156,7 +158,7 @@ |
208 | configure your system to work with Launchpad. This section will focus |
209 | on the following topics: |
210 | |
211 | - * What Launchpad is, and creating a Launchpad account |
212 | + * What Launchpad is and creating a Launchpad account |
213 | * Uploading your GPG and SSH keys to Launchpad |
214 | * Configuring Bazaar to work with Launchpad |
215 | * Configuring Bash to work with Bazaar |
216 | @@ -175,6 +177,9 @@ |
217 | information. This will allow you to download and upload code, submit bug |
218 | reports, and more. |
219 | |
220 | +Besides hosting Ubuntu, Launchpad can host any Free Software project. For more |
221 | +information see the `Launchpad Help wiki <https://help.launchpad.net/>`_. |
222 | + |
223 | |
224 | Get a Launchpad account |
225 | -------------------------- |
226 | @@ -212,8 +217,8 @@ |
227 | sub 4096R/51FBE68C 2010-12-06 |
228 | |
229 | |
230 | -Head to https://launchpad.net/people/+me/+editpgpkeys and copy the part about |
231 | -your "Key fingerprint" into the text box. In the case above this would be |
232 | +Head to https://launchpad.net/people/+me/+editpgpkeys and copy the "Key |
233 | +fingerprint" into the text box. In the case above this would be |
234 | ``5C28 0144 FB08 91C0 2CF3 37AC 6F0B F90F 43CD E61D``. Now click on "Import |
235 | Key". |
236 | |
237 | @@ -253,7 +258,9 @@ |
238 | ---------------- |
239 | |
240 | Bazaar is the tool we use to store code changes in a logical way, to exchange |
241 | -proposed changes and merge them, even if development is done concurrently. |
242 | +proposed changes and merge them, even if development is done concurrently. It |
243 | +is used for the new Ubuntu Distributed Development method of working with |
244 | +Ubuntu packages. |
245 | |
246 | To tell Bazaar who you are, simply run:: |
247 | |
248 | @@ -278,7 +285,6 @@ |
249 | $ export DEBFULLNAME="Bob Dobbs" |
250 | $ export DEBEMAIL="subgenius@example.com" |
251 | |
252 | - |
253 | Now save the file and either restart your terminal or run:: |
254 | |
255 | $ source ~/.bashrc |
256 | |
257 | === modified file 'index.rst' |
258 | --- index.rst 2011-04-21 14:53:48 +0000 |
259 | +++ index.rst 2011-07-15 09:23:07 +0000 |
260 | @@ -3,27 +3,45 @@ |
261 | You can adapt this file completely to your liking, but it should at least |
262 | contain the root `toctree` directive. |
263 | |
264 | -Welcome to ubuntu-packaging-guide's documentation! |
265 | +Ubuntu Packaging Guide |
266 | ================================================== |
267 | |
268 | The guide is split up into two sections: |
269 | |
270 | -* A list of articles based on tasks, so things you want to get done. |
271 | +* A list of articles based on tasks, things you want to get done. |
272 | * A set of :doc:`knowledge base</knowledge-base>` articles that dig deeper |
273 | into specific bits of our tools and workflows. |
274 | |
275 | +Articles |
276 | +-------- |
277 | + |
278 | .. toctree:: |
279 | :maxdepth: 1 |
280 | |
281 | introduction-to-ubuntu-development |
282 | getting-set-up |
283 | fixing-a-bug |
284 | - knowledge-base |
285 | + |
286 | +Knowledge Base |
287 | +-------------- |
288 | + |
289 | +.. toctree:: |
290 | + :maxdepth: 1 |
291 | + |
292 | + debian-dir-overview |
293 | + testing |
294 | + udd-intro |
295 | + udd-working |
296 | + udd-sponsorship |
297 | + udd-uploading |
298 | + udd-latest |
299 | + udd-merging |
300 | + udd-patchsys |
301 | + udd-newpackage |
302 | |
303 | |
304 | Indices and tables |
305 | ================== |
306 | |
307 | * :ref:`genindex` |
308 | -* :ref:`modindex` |
309 | * :ref:`search` |
310 | |
311 | === modified file 'introduction-to-ubuntu-development.rst' |
312 | --- introduction-to-ubuntu-development.rst 2011-02-04 16:44:21 +0000 |
313 | +++ introduction-to-ubuntu-development.rst 2011-07-15 09:23:07 +0000 |
314 | @@ -13,11 +13,11 @@ |
315 | |
316 | Every time a new version of an application is released, or when someone makes |
317 | a change to the source code that goes into Ubuntu, the source package must be |
318 | -uploaded to the build machines to be compiled. The resulting binary packages |
319 | -then are distributed to the archive and its mirrors in different countries. |
320 | -The URLs in ``/etc/apt/sources.list`` point to an archive or mirror. Every |
321 | -day CD images are built for a selection of different Ubuntu flavours. Ubuntu |
322 | -Desktop, Ubuntu Server, Kubuntu and others specify a list of required |
323 | +uploaded to Launchpad's build machines to be compiled. The resulting binary |
324 | +packages then are distributed to the archive and its mirrors in different |
325 | +countries. The URLs in ``/etc/apt/sources.list`` point to an archive or mirror. |
326 | +Every day CD images are built for a selection of different Ubuntu flavours. |
327 | +Ubuntu Desktop, Ubuntu Server, Kubuntu and others specify a list of required |
328 | packages that get on the CD. These CD images are then used for installation |
329 | tests and provide the feedback for further release planning. |
330 | |
331 | |
332 | === removed file 'knowledge-base.rst' |
333 | --- knowledge-base.rst 2011-06-03 09:49:34 +0000 |
334 | +++ knowledge-base.rst 1970-01-01 00:00:00 +0000 |
335 | @@ -1,27 +0,0 @@ |
336 | -============================================ |
337 | -Knowledge base of the Ubuntu Packaging Guide |
338 | -============================================ |
339 | - |
340 | -Table of Contents: |
341 | - |
342 | -* General |
343 | - |
344 | - .. toctree:: |
345 | - :maxdepth: 1 |
346 | - |
347 | - debian-dir-overview |
348 | - testing |
349 | - |
350 | -* Development Processes |
351 | - |
352 | - .. toctree:: |
353 | - :maxdepth: 1 |
354 | - |
355 | - udd-intro |
356 | - udd-working |
357 | - udd-sponsorship |
358 | - udd-uploading |
359 | - udd-latest |
360 | - udd-merging |
361 | - udd-patchsys |
362 | - udd-newpackage |
363 | |
364 | === modified file 'udd-intro.rst' |
365 | --- udd-intro.rst 2011-06-03 20:17:00 +0000 |
366 | +++ udd-intro.rst 2011-07-15 09:23:07 +0000 |
367 | @@ -1,43 +1,36 @@ |
368 | -============================== |
369 | -Ubuntu Distributed Development |
370 | -============================== |
371 | +=================================================== |
372 | +Ubuntu Distributed Development - Getting the Source |
373 | +=================================================== |
374 | |
375 | *Ubuntu Distributed Development* (UDD) is a technique for developing Ubuntu |
376 | packages that uses tools, processes, and workflows similar to generic |
377 | -distributed version control (dVCS) system-based software development. The |
378 | -dVCS used for UDD is Bazaar_. |
379 | +distributed version control system (DVCS) based software development. The |
380 | +DVCS used for UDD is Bazaar_. |
381 | |
382 | -You should already be familiar with basic Bazaar usage and workflow. Ubuntu |
383 | -Intrepid_ or later is required for these instructions to work. |
384 | +You should already be familiar with basic Bazaar usage and workflow. For an |
385 | +introduction to Bazaar see the `Bazaar Five Minute Tutorial |
386 | +<http://doc.bazaar.canonical.com/bzr.dev/en/mini-tutorial/index.html>`_ and the |
387 | +`Bazaar Users Guide |
388 | +<http://doc.bazaar.canonical.com/bzr.dev/en/user-guide/index.html>`_. |
389 | |
390 | |
391 | Source package URLs |
392 | =================== |
393 | |
394 | -Bazaar provides some very nice shortcuts for accessing the source branches of |
395 | -packages in both Ubuntu and Debian (on Launchpad). These shortcuts are |
396 | -available in Bazaar version 2.3 or newer. You can still access source |
397 | -branches in older versions of Bazaar, using a slightly more verbose syntax. |
398 | - |
399 | -The examples in this guide always use the ``ubuntu:`` prefix. |
400 | - |
401 | - |
402 | -Source branch shortcuts |
403 | ------------------------ |
404 | +Bazaar provides some very nice shortcuts for accessing Launchpad's source |
405 | +branches of packages in both Ubuntu and Debian. |
406 | |
407 | To refer to source branches use:: |
408 | |
409 | ubuntu:package |
410 | |
411 | where *package* refers to the package name you're interested in. This URL |
412 | -refers to the package in the current development version of Ubuntu. As of |
413 | -this writing (2011-02-04) that version is Natty_ which will be released as |
414 | -Ubuntu 11.04. Thus, to refer to the branch of Tomboy in Natty, you would |
415 | -use:: |
416 | +refers to the package in the current development version of Ubuntu. To |
417 | +refer to the branch of Tomboy in the development version, you would use:: |
418 | |
419 | ubuntu:tomboy |
420 | |
421 | -To refer to the version of a source package in an older release of ubuntu, |
422 | +To refer to the version of a source package in an older release of Ubuntu, |
423 | just prefix the package name with the release's code name. E.g. to refer to |
424 | Tomboy's source package in Maverick_ use:: |
425 | |
426 | @@ -58,28 +51,8 @@ |
427 | debianlp:lenny/tomboy |
428 | |
429 | |
430 | -Explicit source branches |
431 | ------------------------- |
432 | - |
433 | -If you're using an older version of Bazaar, the ``ubuntu:`` and ``debianlp:`` |
434 | -prefixes won't be available to you. Instead use the ``lp:`` prefix to access |
435 | -the source branch. For example, Tomboy in the latest Ubuntu development |
436 | -release is available at:: |
437 | - |
438 | - lp:ubuntu/tomboy |
439 | - |
440 | -while the Maverick version is available at:: |
441 | - |
442 | - lp:ubuntu/maverick/tomboy |
443 | - |
444 | -and the Debian Lenny version is available at:: |
445 | - |
446 | - lp:debian/lenny/tomboy |
447 | - |
448 | - |
449 | .. _`Bazaar`: http://bazaar.canonical.com/en/ |
450 | .. _`Intrepid`: https://wiki.ubuntu.com/IntrepidIbex |
451 | -.. _Natty: https://wiki.ubuntu.com/NattyNarwhal |
452 | .. _Maverick: https://wiki.ubuntu.com/MaverickMeerkat |
453 | .. _Lenny: http://debian.org/releases/stable/ |
454 | |
455 | @@ -123,7 +96,7 @@ |
456 | ensure that the import is up-to-date. To find the tag of the last revision |
457 | committed by the package importer, do:: |
458 | |
459 | - $ bzr log -l 1 ubuntu:tomboy | grep ^tags: |
460 | + $ bzr log ubuntu:tomboy | grep ^tags | head -n 1 |
461 | tags: 1.5.2-1ubuntu4 |
462 | |
463 | By comparing the version number returned by ``rmadison`` and the tag added by |
464 | @@ -131,20 +104,20 @@ |
465 | is up-to-date. |
466 | |
467 | Here's an example of a package that is out-of-date. Let's say you want to fix |
468 | -a problem in the ``initscripts`` binary package on Natty_. First find out the |
469 | +a problem in the ``initscripts`` binary package. First find out the |
470 | latest binary package versions that are available:: |
471 | |
472 | - $ rmadison initscripts | grep natty |
473 | - initscripts | 2.87dsf-4ubuntu19 | natty | amd64, i386 |
474 | + $ rmadison initscripts | tail -n 1 |
475 | + initscripts | 2.87dsf-4ubuntu25 | oneiric | amd64, i386 |
476 | |
477 | Then determine the source package corresponding to this binary package:: |
478 | |
479 | - $ apt-cache show initscripts | grep ^Source: |
480 | - Source: sysvinit |
481 | + $ apt-cache showsrc initscripts | grep ^Package: |
482 | + Package: sysvinit |
483 | |
484 | Find the latest tag added by the package importer:: |
485 | |
486 | - $ bzr log -l 1 ubuntu:sysvinit | grep ^tags: |
487 | + $ bzr log ubuntu:sysvinit | grep ^tags | head -n 1 |
488 | tags: 2.86.ds1-61ubuntu13 |
489 | |
490 | Here we can see that ``2.86.ds1-61ubuntu13`` is older than |
491 | @@ -155,6 +128,9 @@ |
492 | When you find such out-of-date packages, be sure to `file a bug on the UDD |
493 | project`_ to get the issue resolved. |
494 | |
495 | +A feature in progress is for a warning to be automatically printed when |
496 | +branching an out of date import, this will make the above obsolete. |
497 | + |
498 | .. _branching: |
499 | |
500 | Creating a shared repository |
501 | @@ -173,20 +149,21 @@ |
502 | You will see that a `tomboy` directory is created in your current working |
503 | area. Change to this new directory for the rest of your work:: |
504 | |
505 | - $ cd foobar |
506 | + $ cd tomboy |
507 | |
508 | |
509 | Getting the trunk branch |
510 | ------------------------ |
511 | |
512 | We use the `bzr branch` command to create a local branch of the package. |
513 | -We'll name the target directory `natty` just to keep things easy to remember:: |
514 | - |
515 | - $ bzr branch ubuntu:tomboy natty |
516 | - |
517 | -The `natty` directory represents the version of Tomboy in Natty, and you can |
518 | -always ``cd`` into this directory and do a `bzr pull` to get any future |
519 | -updates. |
520 | +We'll name the target directory `tomboy.dev` just to keep things easy to |
521 | +remember:: |
522 | + |
523 | + $ bzr branch ubuntu:tomboy tomboy.dev |
524 | + |
525 | +The tomboy.dev directory represents the version of Tomboy in the development |
526 | +version of Ubuntu, and you can always ``cd`` into this directory and do a `bzr |
527 | +pull` to get any future updates. |
528 | |
529 | |
530 | Getting a branch for a particular release |
531 | @@ -211,7 +188,7 @@ |
532 | `tomboy` directory created above):: |
533 | |
534 | $ bzr init-repo newpackage |
535 | - $ cd new-package |
536 | + $ cd newpackage |
537 | $ bzr init debian |
538 | $ cd debian |
539 | $ bzr import-dsc http://ftp.de.debian.org/debian/pool/main/n/newpackage/newpackage_1.0-1.dsc |
540 | |
541 | === modified file 'udd-latest.rst' |
542 | --- udd-latest.rst 2011-05-20 15:26:22 +0000 |
543 | +++ udd-latest.rst 2011-07-15 09:23:07 +0000 |
544 | @@ -12,7 +12,7 @@ |
545 | Updating your copy of a branch that corresponds to the package in a particular |
546 | release is very simple, simply use `bzr pull` from the appropriate directory:: |
547 | |
548 | - $ cd tomboy/natty |
549 | + $ cd tomboy/tomboy.dev |
550 | $ bzr pull |
551 | |
552 | This works wherever you have a checkout of a branch, so it will work for |
553 | @@ -39,7 +39,7 @@ |
554 | have committed your current work first:: |
555 | |
556 | $ cd tomboy/bug-12345 |
557 | - $ bzr merge-package ../natty |
558 | + $ bzr merge-package ../tomboy.dev |
559 | |
560 | Any conflicts will be reported, and you can fix them up. To review the |
561 | changes that you just merged use `bzr diff`. To undo the merge use `bzr |
562 | |
563 | === modified file 'udd-merging.rst' |
564 | --- udd-merging.rst 2011-05-27 18:02:49 +0000 |
565 | +++ udd-merging.rst 2011-07-15 09:23:07 +0000 |
566 | @@ -1,6 +1,6 @@ |
567 | -======= |
568 | -Merging |
569 | -======= |
570 | +=========================================== |
571 | +Merging - Updating from Debian and Upstream |
572 | +=========================================== |
573 | |
574 | Merging is one of the strengths of Bazaar, and something we do often in Ubuntu |
575 | development. Updates can be merged from Debian, from a new upstream release, |
576 | @@ -47,7 +47,7 @@ |
577 | need, you will add a new changelog entry, and commit:: |
578 | |
579 | $ dch -i |
580 | - $ debcommit |
581 | + $ bzr commit |
582 | |
583 | as described earlier. |
584 | |
585 | @@ -68,8 +68,8 @@ |
586 | If you are going to build the source package from this merged branch, you |
587 | would use the ``-S`` option to the ``bd`` command. One other thing you'll |
588 | want to consider is also using the ``--package-merge`` option. This will add |
589 | -the appropriate ``-v`` and ``-sa`` options to the source package so that all |
590 | -the changelog entries since the last Ubuntu change will be included in your |
591 | +the appropriate ``-v`` and ``-sa`` options to the source package so that all the |
592 | +changelog entries since the last Ubuntu change will be included in your |
593 | ``_source.changes`` file. For example:: |
594 | |
595 | $ bzr bd -S --package-merge |
596 | @@ -101,9 +101,8 @@ |
597 | |
598 | The last parameter is the location of the tarball that you are upgrading to; |
599 | this can either be a local filesystem path, or a http, ftp, sftp, etc. URI as |
600 | -shown. The command will automatically download the tarball for you. If you |
601 | -point to a `.tar.bz2` or similar tarball then it will recompress it as needed, |
602 | -or convert it if you pass it a `.zip` or similar. |
603 | +shown. The command will automatically download the tarball for you. The |
604 | +tarball will be renamed appropriately and, if required, converted to .gz. |
605 | |
606 | The `merge-upstream` command will either tell you that it completed |
607 | successfully, or that there were conflicts. Either way you will be able to |
608 | @@ -113,7 +112,7 @@ |
609 | not previously used the UDD layout, `bzr merge-upstream` will fail with an |
610 | error that the tag for the previous upstream version is not available; the |
611 | merge can't be completed without knowing what base version to merge against. |
612 | -To work around this, create a tag in your existing existing repo for the last |
613 | +To work around this, create a tag in your existing repository for the last |
614 | upstream version present there; e.g., if the last Ubuntu release was |
615 | *1.1-0ubuntu3*, create the tag *upstream-1.1* pointing to the bzr revision you |
616 | want to use as the tip of the upstream branch. |
617 | |
618 | === modified file 'udd-patchsys.rst' |
619 | --- udd-patchsys.rst 2011-02-05 01:02:31 +0000 |
620 | +++ udd-patchsys.rst 2011-07-15 09:23:07 +0000 |
621 | @@ -1,9 +1,14 @@ |
622 | -=========================== |
623 | -Working with a patch system |
624 | -=========================== |
625 | +============================================================== |
626 | +Ubuntu Distributed Development - Working with Patches via Loom |
627 | +============================================================== |
628 | + |
629 | +Here are some guidelines for working with Quilt_ patches using the Bazaar Loom |
630 | +plugin. A loom allows the development of multiple patches at once, while still |
631 | +giving each patch a branch of its own. This is a work in progress for the UDD |
632 | +developers who will be working on improving this workflow. |
633 | |
634 | Many existing packages that have changes from upstream express those changes |
635 | -using a `patch system`_, of which there are several to choose from. Usually, |
636 | +using a patch system, of which there are several to choose from. Usually, |
637 | when you make an additional change to a package, you'll want to add a patch |
638 | file to the patch system being used, rather than editing the source code in |
639 | place. Note however that it is considered bad practice to add a patch system |
640 | @@ -19,11 +24,6 @@ |
641 | problems pushing and pulling your threads to Launchpad.* Do ``bzr plugins`` to |
642 | find the version you're using. |
643 | |
644 | -Here are some guidelines that I've found helpful. Clearly the existing tools |
645 | -can be improved, but for now this seems to work well enough. This assumes |
646 | -you're using looms to develop your patch, and that the package itself uses the |
647 | -quilt_ patch system. |
648 | - |
649 | One important thing to know: all source branches reflect the tree after a |
650 | ``quilt push -a``. In other words, when you branch a source branch, you get |
651 | the tree with all patches applied, ready for you to jump right into hacking. |
652 | @@ -182,7 +182,6 @@ |
653 | There's now `a bug` that tracks this. |
654 | |
655 | |
656 | -.. _`patch system`: https://wiki.ubuntu.com/DistributedDevelopment/Documentation/PatchSystem/PackagingGuide/PatchSystems |
657 | .. _`Bazaar looms`: https://launchpad.net/bzr-loom |
658 | .. _quilt: http://www.wzdftpd.net/blog/index.php?2008/02/05/3-quilt-a-patch-management-system-how-to-survive-with-many-patches |
659 | .. _`currently includes any existing .pc directory`: https://bugs.launchpad.net/udd/+bug/672740 |
660 | |
661 | === modified file 'udd-sponsorship.rst' |
662 | --- udd-sponsorship.rst 2011-02-07 15:34:46 +0000 |
663 | +++ udd-sponsorship.rst 2011-07-15 09:23:07 +0000 |
664 | @@ -1,6 +1,6 @@ |
665 | -============================== |
666 | -Seeking Review and Sponsorship |
667 | -============================== |
668 | +=============================================================== |
669 | +Ubuntu Distributed Development - Seeking Review and Sponsorship |
670 | +=============================================================== |
671 | |
672 | One of the biggest advantages to using the UDD workflow is to improve quality |
673 | by seeking review of changes by your peers. This is true whether or not you |
674 | @@ -18,8 +18,8 @@ |
675 | Pushing to Launchpad |
676 | ==================== |
677 | |
678 | -We previously showed you how to :ref:`link your branch to the bug |
679 | -<link-via-changelog>` using ``dch`` and ``debcommit``. However, the branch |
680 | +We previously showed you how to :ref:`associate your branch to the bug |
681 | +<link-via-changelog>` using ``dch`` and ``bzr commit``. However, the branch |
682 | and bug don't actually get linked until you push the branch to Launchpad. |
683 | |
684 | It is not critical to have a link to a bug for every change you make, |
685 | @@ -27,14 +27,14 @@ |
686 | |
687 | The general form of the URL you should push your branch to is:: |
688 | |
689 | - lp:~<user-id>/ubuntu/<distroseries>/<package>/bug-12345 |
690 | + lp:~<user-id>/ubuntu/<distroseries>/<package>/<branch-name> |
691 | |
692 | For example, to push your fix for bug 12345 in the Tomboy package for Natty, |
693 | you'd use:: |
694 | |
695 | $ bzr push lp:~subgenius/ubuntu/natty/tomboy/bug-12345 |
696 | |
697 | -The last component of the path is actually arbitrary; it's up to you to pick |
698 | +The last component of the path is arbitrary; it's up to you to pick |
699 | something meaningful. |
700 | |
701 | However, this usually isn't enough to get Ubuntu developers to review and |
702 | @@ -66,7 +66,7 @@ |
703 | debdiff, you can generate one like this (from inside your `bug-12345` |
704 | branch):: |
705 | |
706 | - $ bzr diff -rbranch:../natty |
707 | + $ bzr diff -rbranch:../tomboy.dev |
708 | |
709 | Another way is to is to open the merge proposal and download the diff. |
710 | |
711 | @@ -94,6 +94,6 @@ |
712 | and asking for re-review, or you can reply on the merge proposal page in |
713 | Launchpad. |
714 | |
715 | -Note that if you are sponsored via debdiff attached to a bug report you need |
716 | +Note that if you are sponsored via a debdiff attached to a bug report you need |
717 | to manually update by generating a new diff and attaching that to the bug |
718 | report. |
719 | |
720 | === modified file 'udd-uploading.rst' |
721 | --- udd-uploading.rst 2011-05-25 14:08:46 +0000 |
722 | +++ udd-uploading.rst 2011-07-15 09:23:07 +0000 |
723 | @@ -4,7 +4,7 @@ |
724 | |
725 | Once your merge proposal is reviewed and approved, you will want to upload |
726 | your package, either to the archive (if you have permission) or to your |
727 | -*`Personal Package Archive`_* (PPA). You might also want to do an upload if |
728 | +`Personal Package Archive`_ (PPA). You might also want to do an upload if |
729 | you are sponsoring someone else's changes. |
730 | |
731 | |
732 | @@ -16,17 +16,18 @@ |
733 | then upload it. |
734 | |
735 | First, you need to check that you have the latest version of the package in |
736 | -your checkout of the development package:: |
737 | +your checkout of the development package trunk:: |
738 | |
739 | - $ cd tomboy/natty |
740 | + $ cd tomboy/tomboy.dev |
741 | $ bzr pull |
742 | |
743 | This pulls in any changes that may have been committed while you were working |
744 | on your fix. From here, you have several options. If the changes on the |
745 | -trunk are large, and it will take a while to merge them and test the package, |
746 | -then you can merge them back into your working branch to do this. If not, |
747 | -then you can carry on merging your working branch to the main one. You'll |
748 | -want to use the Bazaar ``merge-package`` command rather than just ``merge``:: |
749 | +trunk are large and you feel should be tested along with your change you can |
750 | +merge them into your bug fix branch and test there. If not, |
751 | +then you can carry on merging your bug fix branch into the development trunk |
752 | +branch. You'll want to use the Bazaar ``merge-package`` command rather than just |
753 | +``merge``:: |
754 | |
755 | $ bzr merge-package ../bug-12345 |
756 | |
757 | @@ -41,26 +42,18 @@ |
758 | before you upload the source package. |
759 | |
760 | The next step is to build and test the modified source package as you normally |
761 | -would. Once you are happy with the upload then you should `dput` the |
762 | -source package. For example, if you want to upload your changes to your PPA, |
763 | -then you'd do:: |
764 | - |
765 | - $ dput ppa:imasponsor/myppa tomboy_1.5.2-1ubuntu5_source.changes |
766 | - |
767 | -or, if you have permission to upload to the primary archive:: |
768 | - |
769 | - $ dput tomboy_1.5.2-1ubuntu5_source.changes |
770 | - |
771 | -You might want to do one more `debcommit` to make sure all your changes are |
772 | -committed in your working tree. |
773 | +would:: |
774 | + |
775 | + $ bzr bd -S |
776 | |
777 | The last step is to mark the change as being the same as the source package |
778 | -that was uploaded, so run:: |
779 | - |
780 | - $ bzr mark-uploaded |
781 | - |
782 | -This also tells the package importer that what is in the Bazaar branch is the |
783 | -same as in the archive. |
784 | +that was uploaded, bzr-builddeb will override the `tag` command to |
785 | +automatically tag with the version number in debian/changelog so run:: |
786 | + |
787 | + $ bzr tag |
788 | + |
789 | +This tag will tell the package importer that what is in the Bazaar branch |
790 | +is the same as in the archive. |
791 | |
792 | Now you can push the changes back to Launchpad:: |
793 | |
794 | @@ -68,6 +61,16 @@ |
795 | |
796 | (Change the destination if you are uploading an SRU or similar.) |
797 | |
798 | +Once you are happy with the upload then you should use `dput` to upload the |
799 | +built source package to Launchpad. For example, if you want to upload your |
800 | +changes to your PPA, then you'd do:: |
801 | + |
802 | + $ dput ppa:imasponsor/myppa tomboy_1.5.2-1ubuntu5_source.changes |
803 | + |
804 | +or, if you have permission to upload to the primary archive:: |
805 | + |
806 | + $ dput ubuntu tomboy_1.5.2-1ubuntu5_source.changes |
807 | + |
808 | You are now free to delete your feature branch, as it is merged, and can |
809 | be re-downloaded from Launchpad if needed. |
810 | |
811 | |
812 | === modified file 'udd-working.rst' |
813 | --- udd-working.rst 2011-02-05 01:02:31 +0000 |
814 | +++ udd-working.rst 2011-07-15 09:23:07 +0000 |
815 | @@ -1,6 +1,6 @@ |
816 | -==================== |
817 | -Working on a Package |
818 | -==================== |
819 | +===================================================== |
820 | +Ubuntu Distributed Development - Working on a Package |
821 | +===================================================== |
822 | |
823 | Once you have the source package branch in a shared repository, you'll want to |
824 | create additional branches for the fixes or other work you plan to do. You'll |
825 | @@ -15,7 +15,7 @@ |
826 | The first thing to do is to make sure your source package branch is |
827 | up-to-date. It will be if you just checked it out, otherwise do this:: |
828 | |
829 | - $ cd natty |
830 | + $ cd tomboy.dev |
831 | $ bzr pull |
832 | |
833 | Any updates to the package that have uploaded since your checkout will now be |
834 | @@ -25,7 +25,7 @@ |
835 | repository you previously created for Tomboy, you can create your bug fix |
836 | branch like this:: |
837 | |
838 | - $ bzr branch natty bug-12345 |
839 | + $ bzr branch tomboy.dev bug-12345 |
840 | $ cd bug-12345 |
841 | |
842 | Now you can do all my work in the `bug-12345` directory. You make changes |
843 | @@ -41,9 +41,8 @@ |
844 | |
845 | .. _link-via-changelog: |
846 | |
847 | -Here's where things diverge a little from typical Bazaar usage. When you |
848 | -added your `debian/changelog` entry, you should have included a bug fix tag |
849 | -that indicated which Launchpad bug issue you're fixing. The format of this |
850 | +When you added your `debian/changelog` entry, you should have included a bug fix |
851 | +tag that indicated which Launchpad bug issue you're fixing. The format of this |
852 | textual tag is pretty strict: ``LP: #12345``. The space between the ``:`` and |
853 | the ``#`` is required and of course the number will be replaced by the actual |
854 | bug number you're fixing. Your `debian/changelog` entry might look something |
855 | @@ -55,18 +54,15 @@ |
856 | |
857 | -- Bob Dobbs <subgenius@example.com> Mon, 10 Jan 2011 16:10:01 -0500 |
858 | |
859 | -Normally, when you want to commit changes to your branch, you just use ``bzr |
860 | -commit``, but in the case where you've made a change to ``debian/changelog``, |
861 | -you'll want to use the ``debcommit`` command instead:: |
862 | - |
863 | - $ debcommit |
864 | - |
865 | -The reason to use ``debcommit`` instead is that it automatically includes your |
866 | -``debian/changelog`` entry in the commit message, and it also adds the |
867 | -necessary metadata to link your branch to the bug report when you push your |
868 | -branch to Launchpad. You can do that manually with ``bzr commit`` (and |
869 | -eventually, ``bzr commit`` may get smart enough to do it for you), but for now |
870 | -``debcommit`` is the most convenient way to do it. |
871 | +Commit with the normal:: |
872 | + |
873 | + bzr commit |
874 | + |
875 | +A hook in bzr-builddeb will use the debian/changelog text as the commit |
876 | +message and set the tag to mark bug #12345 as fixed. |
877 | + |
878 | +This only works with bzr-builddeb 2.7.5 and bzr 2.4, for older versions use |
879 | +`debcommit`. |
880 | |
881 | |
882 | Building the package |
883 | @@ -95,16 +91,5 @@ |
884 | Note that while `bzr bd` has a `--native` switch, it does not have a |
885 | `--no-native` switch. |
886 | |
887 | -You might also see an error that looks something like this: |
888 | - |
889 | - dpkg-source: error: Version number suggests Ubuntu changes, but |
890 | - Maintainer: does not have Ubuntu address |
891 | - |
892 | -In a sense, this is a safeguard to ensure that ``update-maintainer`` is run |
893 | -when necessary. However in this case, you can just temporarily set the |
894 | -``$DEBEMAIL`` environment variable to a non-@ubuntu.com address:: |
895 | - |
896 | - $ DEBEMAIL='me@example.com' bzr bd -S |
897 | - |
898 | Once you've got the source package, you can build it as normal with |
899 | -``pbuilder`` or ``sbuild``. |
900 | +``pbuilder-dist`` (or ``pbuilder`` or ``sbuild``). |
Thanks a lot for your fixes and your attention to detail.
I have a few quick questions though:
- Why do you remove the section about libvigraimpex?
- bzr commit instead of debcommit? (debcommit does much more than just 'bzr commit')
- Do you think it makes sense to have two copies of the knowledge base article index?
- the section following "Then determine the source package corresponding to this binary package::" seems to have been correct before.
- Why do you leave the link to intrepid and remove the link to natty? (line 419)
- Is "bzr tag" necessary nowadays?
- Why do you remove the "update-maintainer" bits?