Merge lp:~jr/ubuntu-packaging-guide/fixes into lp:ubuntu-packaging-guide

[Jonathan Riddell]

A bunch of fixes to tidy up parts of the packaging guide

[Daniel Holbach (dholbach)]

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?

review: Needs Information

[Jonathan Riddell (jr)]

 - 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.

[lp:~jr/ubuntu-packaging-guide/fixes]

61. By Jonathan Riddell on 2011-07-15

remove duplicate knowledge base index

[Barry Warsaw (barry)]

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.

review: Approve

[Morten Kjeldgaard (mok0)]

> - 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)]

Could it be that a result of this merge there's a couple of warnings now?

daniel@miyazaki:~/bzr/ubuntu-packaging-guide$ make html
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/bzr/ubuntu-packaging-guide/fixing-a-bug-security.rst:196: (ERROR/3) Unexpected indentation.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] udd-working
/home/daniel/bzr/ubuntu-packaging-guide/fixing-a-bug-security.rst:72: WARNING: unknown document: /udd-intro.rst
/home/daniel/bzr/ubuntu-packaging-guide/index.rst:12: WARNING: unknown document: /knowledge-base
writing additional files... genindex search
copying images... [100%] images/cycle-items.png
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@miyazaki:~/bzr/ubuntu-packaging-guide$

Shall I file a bug?

[Jonathan Riddell (jr)]

index.rst warning fixed

I also fixed the incorrect link in the unrelated fixing-a-bug-security.rst document

I've no idea how to fix the indentation in the fixing-a-bug-security.rst document, restructuredtext is weird like that

[Daniel Holbach (dholbach)]

After a paragraph ending with "::" (indicating a following paragraph in preformatted text), it needs a newline. I fixed that bit in fixing-a-bug-security.rst and pushed it. Things are nice and dandy again. Thanks!

daniel@miyazaki:~/bzr/ubuntu-packaging-guide$ make html
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/cycle-items.png
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in _build/html.
daniel@miyazaki:~/bzr/ubuntu-packaging-guide$

=== modified file 'debian-dir-overview.rst'
--- debian-dir-overview.rst	2011-06-01 08:05:03 +0000
+++ debian-dir-overview.rst	2011-07-15 09:23:07 +0000
@@ -59,7 +59,7 @@
 number) appended to the end of the Debian version. So if the Debian hello 
 ``2.6-1`` package was changed by Ubuntu, the version string would be 
 ``2.6-1ubuntu1``. If a package for the application does not exist in Debian, 
-then the Debian revision is ``0`` (e.g., ``2.6-0ubuntu1``).
+then the Debian revision is ``0`` (e.g. ``2.6-0ubuntu1``).
 
 For further information, see the `changelog section (Section 4.4) 
 <http://www.debian.org/doc/debian-policy/ch-source.html#s-dpkgchangelog>`_ of 
@@ -115,7 +115,7 @@
 Maintainer Field spec <https://wiki.ubuntu.com/DebianMaintainerField>`_ on the 
 Ubuntu wiki.
 
-Each additional paragraph describes a binary package built.
+Each additional paragraph describes a binary package to be built.
 
 For further information, see the `control file section (Chapter 5) 
 <http://www.debian.org/doc/debian-policy/ch-controlfields.html>`_ of the Debian 
@@ -264,10 +264,12 @@
  foo usr/bin
  debian/bar.desktop usr/share/applications
 
-In the second case, files installed into ``debian/tmp`` can then be moved into 
-separate binary packages using multiple ``$package_name.install`` files. This 
-is often done to split large amounts of architecture independent data out of 
-architecture dependent packages and into ``Architecture: all`` packages. In 
+When a source package is producing multiple binary packages ``dh`` will
+install the files into ``debian/tmp`` rather than directly into
+``debian/<package>``. Files installed into ``debian/tmp`` can then be moved
+into separate binary packages using multiple ``$package_name.install`` files.
+This is often done to split large amounts of architecture independent data out
+of architecture dependent packages and into ``Architecture: all`` packages. In 
 this case, only the name of the files (or directories) to be installed are 
 needed without the installation directory. For example, ``foo.install`` 
 containing only the architecture dependent files might look like::
@@ -319,6 +321,10 @@
 4.11) <http://www.debian.org/doc/debian-policy/ch-source.html#s-debianwatch>`_ 
 of the Debian Policy Manual.
 
+For a list of packages where the ``watch`` file reports they are not in sync
+with upstream see `Ubuntu External Health Status
+<http://qa.ubuntuwire.org/uehs/no_updated.html>`_.
+
 The source/format file
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -327,7 +333,7 @@
 to use the newer 3.0 source format. In this case, the file should contain a 
 single line indicating the desired format:
 
-* ``3.0 (native)`` for Debian native packages or
+* ``3.0 (native)`` for Debian native packages (no upstream version) or
 
 * ``3.0 (quilt)`` for packages with a separate upstream tarball
 
 
=== modified file 'fixing-a-bug.rst'
--- fixing-a-bug.rst	2011-06-03 21:23:43 +0000
+++ fixing-a-bug.rst	2011-07-15 09:23:07 +0000
@@ -19,7 +19,7 @@
 Finding the problem
 ===================
 
-There is a lot of different ways to find things to work on. It might be a bug
+There are a lot of different ways to find things to work on. It might be a bug
 report you are encountering yourself (which gives you a good opportunity to
 test the fix), or a problem you noted elsewhere, maybe in a bug report.
 
@@ -55,28 +55,16 @@
 different binary packages.  To find the source package for a particular binary
 package, type::
 
-    $ apt-cache show tomboy | grep ^Source:
-
-In this case, nothing is printed, meaning that ``tomboy`` is also the name of
-the binary package.  An example where the source and binary package names
-differ is ``python-vigra``.  While that is the binary package name, the source
-package is actually ``libvigraimpex`` and can be found with this command (and
-its output)::
-
-    $ apt-cache show python-vigra | grep ^Source:
-    Source: libvigraimpex
-
-.. XXX: Link to SRU article.
-
+    $ apt-cache showsrc tomboy | grep ^Package:
 
 Getting the code
 ================
 
 Once you know the source package to work on, you will want to get a copy of
-the code on your system, so that you can debug it.  This is done by
-:ref:`*branching* the source package <branching>` branch corresponding to the
-source package.  Launchpad maintains source package branches for all the
-packages in Ubuntu.
+the code on your system, so that you can debug it.  In Ubuntu Distributed
+Development this is done by :ref:`*branching* the source package <branching>`
+branch corresponding to the source package.  Launchpad maintains source package
+branches for all the packages in Ubuntu.
 
 Once you've got a local branch of the source package, you can investigate the
 bug, create a fix, and upload your proposed fix to Launchpad, in the form of a
@@ -84,7 +72,7 @@
 *merge proposal* <merge-proposal>`, which asks other Ubuntu developers to
 review and approve your change.  If they agree with your changes, an Ubuntu
 developer will upload the new version of the package to Ubuntu so that
-everyone gets the benefit or your excellent fix - and you get a little bit of
+everyone gets the benefit of your excellent fix - and you get a little bit of
 credit.  You're now on your way to becoming an Ubuntu developer!
 
 We'll describe specifics on how to branch the code, push your fix, and request
@@ -182,7 +170,7 @@
 
 With the changelog entry written and saved, you can just run::
 
-  debcommit
+  bzr commit
 
 and the change will be committed (locally) with your changelog entry as a 
 commit message.
@@ -206,3 +194,4 @@
 browser. There find the "(+) Propose for merging" link, click it to get the
 change reviewed by somebody and included in Ubuntu.
 
+.. XXX: Link to SRU article.
 
=== modified file 'getting-set-up.rst'
--- getting-set-up.rst	2011-07-12 16:11:03 +0000
+++ getting-set-up.rst	2011-07-15 09:23:07 +0000
@@ -4,8 +4,8 @@
 
 There are a number of things you need to do to get started developing for Ubuntu.
 This article is designed to get your computer set up so that you can start 
-working with packages, and upload your packages to Launchpad. Here's what we'll 
-cover:
+working with packages, and upload your packages to Ubuntu's hosting
+platform, Launchpad. Here's what we'll cover:
 
 * Installing packaging-related software. This includes:
 
@@ -33,7 +33,7 @@
 
 There are a number of tools that will make your life as an Ubuntu developer
 much easier.  You will encounter these tools later in this guide.  To install
-most of the tools you will need, run this command::
+most of the tools you will need run this command::
 
     $ sudo apt-get install gnupg pbuilder ubuntu-dev-tools bzr-builddeb apt-file
 
@@ -55,8 +55,9 @@
 * ``ubuntu-dev-tools`` (and ``devscripts``, a direct dependency) -- a
   collection of tools that make many packaging tasks easier.
 * ``bzr-builddeb`` (and ``bzr``, a dependency) -- distributed version control
-  tools that makes it easy for many developers to collaborate and work on the
-  same code while keeping it trivial to merge each others work.
+  with Bazaar, a new way of working with packages for Ubuntu that will make it
+  easy for many developers to collaborate and work on the same code while
+  keeping it trivial to merge each others work.
 * ``apt-file`` provides an easy way to find the binary package that contains a
   given file.
 * ``apt-cache`` (part of the ``apt`` package) provides even more information 
@@ -84,12 +85,13 @@
 which means the key will never expire. The last questions will be about your
 name and email address. Just pick the ones you are going to use for Ubuntu
 development here, you can add additional email addresses later on. Adding a
-comment is not necessary. Then you will have to set a passphrase. Choose a
-safe one. 
+comment is not necessary. Then you will have to set a passphrase, choose a
+safe one (a passphrase is just a password which is allowed to include spaces). 
 
 Now GPG will create a key for you, which can take a little bit of time; it 
 needs random bytes, so if you give the system some work to do it will be 
-just fine.  Move the cursor around!
+just fine.  Move the cursor around, type some paragraphs of random text, load
+some web page.
 
 Once this is done, you will get a message similar to this one::
 
@@ -107,8 +109,8 @@
 
 This will send your key to one keyserver, but a network of keyservers will 
 automatically sync the key between themselves. Once this syncing is complete, 
-your signed public key will be ready to verify your your contributions 
-around the world.
+your signed public key will be ready to verify your contributions around the
+world.
 
 
 Create your SSH key
@@ -117,10 +119,10 @@
 SSH_ stands for *Secure Shell*, and it is a protocol that allows you to 
 exchange data in a secure way over a network. It is common to use SSH to access 
 and open a shell on another computer, and to use it to securely transfer files. 
-For our purposes, we will mainly be using SSH to securely communicate with 
-Launchpad. 
+For our purposes, we will mainly be using SSH to securely upload source packages
+to Launchpad. 
 
-To generate a SSH key, enter::
+To generate an SSH key, enter::
 
     $ ssh-keygen -t rsa
 
@@ -156,7 +158,7 @@
 configure your system to work with Launchpad. This section will focus
 on the following topics:
 
- * What Launchpad is, and creating a Launchpad account
+ * What Launchpad is and creating a Launchpad account
  * Uploading your GPG and SSH keys to Launchpad
  * Configuring Bazaar to work with Launchpad
  * Configuring Bash to work with Bazaar
@@ -175,6 +177,9 @@
 information. This will allow you to download and upload code, submit bug 
 reports, and more.
 
+Besides hosting Ubuntu, Launchpad can host any Free Software project. For more
+information see the `Launchpad Help wiki <https://help.launchpad.net/>`_.
+
 
 Get a Launchpad account
 --------------------------
@@ -212,8 +217,8 @@
     sub   4096R/51FBE68C 2010-12-06
 
 
-Head to https://launchpad.net/people/+me/+editpgpkeys and copy the part about
-your "Key fingerprint" into the text box. In the case above this would be
+Head to https://launchpad.net/people/+me/+editpgpkeys and copy the "Key
+fingerprint" into the text box. In the case above this would be
 ``5C28 0144 FB08 91C0 2CF3  37AC 6F0B F90F 43CD E61D``. Now click on "Import
 Key".
 
@@ -253,7 +258,9 @@
 ----------------
 
 Bazaar is the tool we use to store code changes in a logical way, to exchange
-proposed changes and merge them, even if development is done concurrently.
+proposed changes and merge them, even if development is done concurrently.  It
+is used for the new Ubuntu Distributed Development method of working with
+Ubuntu packages.
 
 To tell Bazaar who you are, simply run::
 
@@ -278,7 +285,6 @@
     $ export DEBFULLNAME="Bob Dobbs"
     $ export DEBEMAIL="[e-mail]"
 
-
 Now save the file and either restart your terminal or run::
 
     $ source ~/.bashrc
 
=== modified file 'index.rst'
--- index.rst	2011-04-21 14:53:48 +0000
+++ index.rst	2011-07-15 09:23:07 +0000
@@ -3,27 +3,45 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to ubuntu-packaging-guide's documentation!
+Ubuntu Packaging Guide
 ==================================================
 
 The guide is split up into two sections:
 
-* A list of articles based on tasks, so things you want to get done.
+* A list of articles based on tasks, things you want to get done.
 * A set of :doc:`knowledge base</knowledge-base>` articles that dig deeper 
   into specific bits of our tools and workflows.
 
+Articles
+--------
+
 .. toctree::
    :maxdepth: 1
 
    introduction-to-ubuntu-development
    getting-set-up
    fixing-a-bug
-   knowledge-base
+
+Knowledge Base
+--------------
+
+.. toctree::
+   :maxdepth: 1
+
+   debian-dir-overview
+   testing
+   udd-intro
+   udd-working
+   udd-sponsorship
+   udd-uploading
+   udd-latest
+   udd-merging
+   udd-patchsys
+   udd-newpackage
 
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
 
=== modified file 'introduction-to-ubuntu-development.rst'
--- introduction-to-ubuntu-development.rst	2011-02-04 16:44:21 +0000
+++ introduction-to-ubuntu-development.rst	2011-07-15 09:23:07 +0000
@@ -13,11 +13,11 @@
 
 Every time a new version of an application is released, or when someone makes
 a change to the source code that goes into Ubuntu, the source package must be
-uploaded to the build machines to be compiled. The resulting binary packages 
-then are distributed to the archive and its mirrors in different countries. 
-The URLs in ``/etc/apt/sources.list`` point to an archive or mirror.  Every 
-day CD images are built for a selection of different Ubuntu flavours.  Ubuntu 
-Desktop, Ubuntu Server, Kubuntu and others specify a list of required 
+uploaded to Launchpad's build machines to be compiled. The resulting binary
+packages then are distributed to the archive and its mirrors in different
+countries. The URLs in ``/etc/apt/sources.list`` point to an archive or mirror. 
+Every day CD images are built for a selection of different Ubuntu flavours. 
+Ubuntu Desktop, Ubuntu Server, Kubuntu and others specify a list of required 
 packages that get on the CD. These CD images are then used for installation 
 tests and provide the feedback for further release planning.
 
 
=== removed file 'knowledge-base.rst'
--- knowledge-base.rst	2011-06-03 09:49:34 +0000
+++ knowledge-base.rst	1970-01-01 00:00:00 +0000
@@ -1,27 +0,0 @@
-============================================
-Knowledge base of the Ubuntu Packaging Guide
-============================================
-
-Table of Contents:
-
-* General
-
-  .. toctree::
-     :maxdepth: 1
-
-     debian-dir-overview
-     testing
-
-* Development Processes
-  
-  .. toctree::
-     :maxdepth: 1
-
-     udd-intro
-     udd-working
-     udd-sponsorship
-     udd-uploading
-     udd-latest
-     udd-merging
-     udd-patchsys
-     udd-newpackage
 
=== modified file 'udd-intro.rst'
--- udd-intro.rst	2011-06-03 20:17:00 +0000
+++ udd-intro.rst	2011-07-15 09:23:07 +0000
@@ -1,43 +1,36 @@
-==============================
-Ubuntu Distributed Development
-==============================
+===================================================
+Ubuntu Distributed Development - Getting the Source
+===================================================
 
 *Ubuntu Distributed Development* (UDD) is a technique for developing Ubuntu
 packages that uses tools, processes, and workflows similar to generic
-distributed version control (dVCS) system-based software development.  The
-dVCS used for UDD is Bazaar_.
+distributed version control system (DVCS) based software development.  The
+DVCS used for UDD is Bazaar_.
 
-You should already be familiar with basic Bazaar usage and workflow.  Ubuntu
-Intrepid_ or later is required for these instructions to work.
+You should already be familiar with basic Bazaar usage and workflow.  For an
+introduction to Bazaar see the `Bazaar Five Minute Tutorial
+<http://doc.bazaar.canonical.com/bzr.dev/en/mini-tutorial/index.html>`_ and the
+`Bazaar Users Guide
+<http://doc.bazaar.canonical.com/bzr.dev/en/user-guide/index.html>`_.
 
 
 Source package URLs
 ===================
 
-Bazaar provides some very nice shortcuts for accessing the source branches of
-packages in both Ubuntu and Debian (on Launchpad).  These shortcuts are
-available in Bazaar version 2.3 or newer.  You can still access source
-branches in older versions of Bazaar, using a slightly more verbose syntax.
-
-The examples in this guide always use the ``ubuntu:`` prefix.
-
-
-Source branch shortcuts
------------------------
+Bazaar provides some very nice shortcuts for accessing Launchpad's source
+branches of packages in both Ubuntu and Debian.
 
 To refer to source branches use::
 
     ubuntu:package
 
 where *package* refers to the package name you're interested in.  This URL
-refers to the package in the current development version of Ubuntu.  As of
-this writing (2011-02-04) that version is Natty_ which will be released as
-Ubuntu 11.04.  Thus, to refer to the branch of Tomboy in Natty, you would
-use::
+refers to the package in the current development version of Ubuntu.  To
+refer to the branch of Tomboy in the development version, you would use::
 
     ubuntu:tomboy
 
-To refer to the version of a source package in an older release of ubuntu,
+To refer to the version of a source package in an older release of Ubuntu,
 just prefix the package name with the release's code name.  E.g. to refer to
 Tomboy's source package in Maverick_ use::
 
@@ -58,28 +51,8 @@
     debianlp:lenny/tomboy
 
 
-Explicit source branches
-------------------------
-
-If you're using an older version of Bazaar, the ``ubuntu:`` and ``debianlp:``
-prefixes won't be available to you.  Instead use the ``lp:`` prefix to access
-the source branch.  For example, Tomboy in the latest Ubuntu development
-release is available at::
-
-    lp:ubuntu/tomboy
-
-while the Maverick version is available at::
-
-    lp:ubuntu/maverick/tomboy
-
-and the Debian Lenny version is available at::
-
-    lp:debian/lenny/tomboy
-
-
 .. _`Bazaar`: http://bazaar.canonical.com/en/
 .. _`Intrepid`: https://wiki.ubuntu.com/IntrepidIbex
-.. _Natty: https://wiki.ubuntu.com/NattyNarwhal
 .. _Maverick: https://wiki.ubuntu.com/MaverickMeerkat
 .. _Lenny: http://debian.org/releases/stable/
 
@@ -123,7 +96,7 @@
 ensure that the import is up-to-date.  To find the tag of the last revision
 committed by the package importer, do::
 
-    $ bzr log -l 1 ubuntu:tomboy | grep ^tags:
+    $ bzr log ubuntu:tomboy | grep ^tags | head -n 1
     tags: 1.5.2-1ubuntu4
 
 By comparing the version number returned by ``rmadison`` and the tag added by
@@ -131,20 +104,20 @@
 is up-to-date.
 
 Here's an example of a package that is out-of-date.  Let's say you want to fix
-a problem in the ``initscripts`` binary package on Natty_.  First find out the
+a problem in the ``initscripts`` binary package.  First find out the
 latest binary package versions that are available::
 
-    $ rmadison initscripts | grep natty
-    initscripts | 2.87dsf-4ubuntu19 |         natty | amd64, i386
+    $ rmadison initscripts | tail -n 1
+    initscripts | 2.87dsf-4ubuntu25 |       oneiric | amd64, i386
 
 Then determine the source package corresponding to this binary package::
 
-    $ apt-cache show initscripts | grep ^Source:
-    Source: sysvinit
+    $ apt-cache showsrc initscripts | grep ^Package:
+    Package: sysvinit
 
 Find the latest tag added by the package importer::
 
-    $ bzr log -l 1 ubuntu:sysvinit | grep ^tags:
+    $ bzr log ubuntu:sysvinit | grep ^tags | head -n 1
     tags: 2.86.ds1-61ubuntu13
 
 Here we can see that ``2.86.ds1-61ubuntu13`` is older than
@@ -155,6 +128,9 @@
 When you find such out-of-date packages, be sure to `file a bug on the UDD
 project`_ to get the issue resolved.
 
+A feature in progress is for a warning to be automatically printed when
+branching an out of date import, this will make the above obsolete.
+
 .. _branching:
 
 Creating a shared repository
@@ -173,20 +149,21 @@
 You will see that a `tomboy` directory is created in your current working
 area.  Change to this new directory for the rest of your work::
 
-    $ cd foobar
+    $ cd tomboy
 
 
 Getting the trunk branch
 ------------------------
 
 We use the `bzr branch` command to create a local branch of the package.
-We'll name the target directory `natty` just to keep things easy to remember::
-
-    $ bzr branch ubuntu:tomboy natty
-
-The `natty` directory represents the version of Tomboy in Natty, and you can
-always ``cd`` into this directory and do a `bzr pull` to get any future
-updates.
+We'll name the target directory `tomboy.dev` just to keep things easy to
+remember::
+
+    $ bzr branch ubuntu:tomboy tomboy.dev
+
+The tomboy.dev directory represents the version of Tomboy in the development
+version of Ubuntu, and you can always ``cd`` into this directory and do a `bzr
+pull` to get any future updates.
 
 
 Getting a branch for a particular release
@@ -211,7 +188,7 @@
 `tomboy` directory created above)::
 
     $ bzr init-repo newpackage
-    $ cd new-package
+    $ cd newpackage
     $ bzr init debian
     $ cd debian
     $ bzr import-dsc http://ftp.de.debian.org/debian/pool/main/n/newpackage/newpackage_1.0-1.dsc
 
=== modified file 'udd-latest.rst'
--- udd-latest.rst	2011-05-20 15:26:22 +0000
+++ udd-latest.rst	2011-07-15 09:23:07 +0000
@@ -12,7 +12,7 @@
 Updating your copy of a branch that corresponds to the package in a particular
 release is very simple, simply use `bzr pull` from the appropriate directory::
 
-    $ cd tomboy/natty
+    $ cd tomboy/tomboy.dev
     $ bzr pull
 
 This works wherever you have a checkout of a branch, so it will work for
@@ -39,7 +39,7 @@
 have committed your current work first::
 
     $ cd tomboy/bug-12345
-    $ bzr merge-package ../natty
+    $ bzr merge-package ../tomboy.dev
 
 Any conflicts will be reported, and you can fix them up.  To review the
 changes that you just merged use `bzr diff`.  To undo the merge use `bzr
 
=== modified file 'udd-merging.rst'
--- udd-merging.rst	2011-05-27 18:02:49 +0000
+++ udd-merging.rst	2011-07-15 09:23:07 +0000
@@ -1,6 +1,6 @@
-=======
-Merging
-=======
+===========================================
+Merging - Updating from Debian and Upstream
+===========================================
 
 Merging is one of the strengths of Bazaar, and something we do often in Ubuntu
 development.  Updates can be merged from Debian, from a new upstream release,
@@ -47,7 +47,7 @@
 need, you will add a new changelog entry, and commit::
 
     $ dch -i
-    $ debcommit
+    $ bzr commit
 
 as described earlier.
 
@@ -68,8 +68,8 @@
 If you are going to build the source package from this merged branch, you
 would use the ``-S`` option to the ``bd`` command.  One other thing you'll
 want to consider is also using the ``--package-merge`` option.  This will add
-the appropriate ``-v`` and ``-sa`` options to the source package so that all
-the changelog entries since the last Ubuntu change will be included in your
+the appropriate ``-v`` and ``-sa`` options to the source package so that all the
+changelog entries since the last Ubuntu change will be included in your
 ``_source.changes`` file.   For example::
 
     $ bzr bd -S --package-merge
@@ -101,9 +101,8 @@
 
 The last parameter is the location of the tarball that you are upgrading to;
 this can either be a local filesystem path, or a http, ftp, sftp, etc. URI as
-shown.  The command will automatically download the tarball for you.  If you
-point to a `.tar.bz2` or similar tarball then it will recompress it as needed,
-or convert it if you pass it a `.zip` or similar.
+shown.  The command will automatically download the tarball for you.  The
+tarball will be renamed appropriately and, if required, converted to .gz.
 
 The `merge-upstream` command will either tell you that it completed
 successfully, or that there were conflicts.  Either way you will be able to
@@ -113,7 +112,7 @@
 not previously used the UDD layout, `bzr merge-upstream` will fail with an
 error that the tag for the previous upstream version is not available; the
 merge can't be completed without knowing what base version to merge against.
-To work around this, create a tag in your existing existing repo for the last
+To work around this, create a tag in your existing repository for the last
 upstream version present there; e.g., if the last Ubuntu release was
 *1.1-0ubuntu3*, create the tag *upstream-1.1* pointing to the bzr revision you
 want to use as the tip of the upstream branch.
 
=== modified file 'udd-patchsys.rst'
--- udd-patchsys.rst	2011-02-05 01:02:31 +0000
+++ udd-patchsys.rst	2011-07-15 09:23:07 +0000
@@ -1,9 +1,14 @@
-===========================
-Working with a patch system
-===========================
+==============================================================
+Ubuntu Distributed Development - Working with Patches via Loom
+==============================================================
+
+Here are some guidelines for working with Quilt_ patches using the Bazaar Loom
+plugin. A loom allows the development of multiple patches at once, while still
+giving each patch a branch of its own.  This is a work in progress for the UDD
+developers who will be working on improving this workflow.
 
 Many existing packages that have changes from upstream express those changes
-using a `patch system`_, of which there are several to choose from.  Usually,
+using a patch system, of which there are several to choose from.  Usually,
 when you make an additional change to a package, you'll want to add a patch
 file to the patch system being used, rather than editing the source code in
 place.  Note however that it is considered bad practice to add a patch system
@@ -19,11 +24,6 @@
 problems pushing and pulling your threads to Launchpad.* Do ``bzr plugins`` to
 find the version you're using.
 
-Here are some guidelines that I've found helpful.  Clearly the existing tools
-can be improved, but for now this seems to work well enough.  This assumes
-you're using looms to develop your patch, and that the package itself uses the
-quilt_ patch system.
-
 One important thing to know: all source branches reflect the tree after a
 ``quilt push -a``.  In other words, when you branch a source branch, you get
 the tree with all patches applied, ready for you to jump right into hacking.
@@ -182,7 +182,6 @@
 There's now `a bug` that tracks this.
 
 
-.. _`patch system`: https://wiki.ubuntu.com/DistributedDevelopment/Documentation/PatchSystem/PackagingGuide/PatchSystems
 .. _`Bazaar looms`: https://launchpad.net/bzr-loom
 .. _quilt: http://www.wzdftpd.net/blog/index.php?2008/02/05/3-quilt-a-patch-management-system-how-to-survive-with-many-patches
 .. _`currently includes any existing .pc directory`: https://bugs.launchpad.net/udd/+bug/672740
 
=== modified file 'udd-sponsorship.rst'
--- udd-sponsorship.rst	2011-02-07 15:34:46 +0000
+++ udd-sponsorship.rst	2011-07-15 09:23:07 +0000
@@ -1,6 +1,6 @@
-==============================
-Seeking Review and Sponsorship
-==============================
+===============================================================
+Ubuntu Distributed Development - Seeking Review and Sponsorship
+===============================================================
 
 One of the biggest advantages to using the UDD workflow is to improve quality
 by seeking review of changes by your peers.  This is true whether or not you
@@ -18,8 +18,8 @@
 Pushing to Launchpad
 ====================
 
-We previously showed you how to :ref:`link your branch to the bug
-<link-via-changelog>` using ``dch`` and ``debcommit``.  However, the branch
+We previously showed you how to :ref:`associate your branch to the bug
+<link-via-changelog>` using ``dch`` and ``bzr commit``.  However, the branch
 and bug don't actually get linked until you push the branch to Launchpad.
 
 It is not critical to have a link to a bug for every change you make,
@@ -27,14 +27,14 @@
 
 The general form of the URL you should push your branch to is::
 
-    lp:~<user-id>/ubuntu/<distroseries>/<package>/bug-12345
+    lp:~<user-id>/ubuntu/<distroseries>/<package>/<branch-name>
 
 For example, to push your fix for bug 12345 in the Tomboy package for Natty,
 you'd use::
 
     $ bzr push lp:~subgenius/ubuntu/natty/tomboy/bug-12345
 
-The last component of the path is actually arbitrary; it's up to you to pick
+The last component of the path is arbitrary; it's up to you to pick
 something meaningful.
 
 However, this usually isn't enough to get Ubuntu developers to review and
@@ -66,7 +66,7 @@
 debdiff, you can generate one like this (from inside your `bug-12345`
 branch)::
 
-    $ bzr diff -rbranch:../natty
+    $ bzr diff -rbranch:../tomboy.dev
 
 Another way is to is to open the merge proposal and download the diff.
 
@@ -94,6 +94,6 @@
 and asking for re-review, or you can reply on the merge proposal page in
 Launchpad.
 
-Note that if you are sponsored via debdiff attached to a bug report you need
+Note that if you are sponsored via a debdiff attached to a bug report you need
 to manually update by generating a new diff and attaching that to the bug
 report.
 
=== modified file 'udd-uploading.rst'
--- udd-uploading.rst	2011-05-25 14:08:46 +0000
+++ udd-uploading.rst	2011-07-15 09:23:07 +0000
@@ -4,7 +4,7 @@
 
 Once your merge proposal is reviewed and approved, you will want to upload
 your package, either to the archive (if you have permission) or to your
-*`Personal Package Archive`_* (PPA).  You might also want to do an upload if
+`Personal Package Archive`_ (PPA).  You might also want to do an upload if
 you are sponsoring someone else's changes.
 
 
@@ -16,17 +16,18 @@
 then upload it.
 
 First, you need to check that you have the latest version of the package in
-your checkout of the development package::
+your checkout of the development package trunk::
 
-    $ cd tomboy/natty
+    $ cd tomboy/tomboy.dev
     $ bzr pull
 
 This pulls in any changes that may have been committed while you were working
 on your fix.  From here, you have several options.  If the changes on the
-trunk are large, and it will take a while to merge them and test the package,
-then you can merge them back into your working branch to do this.  If not,
-then you can carry on merging your working branch to the main one.  You'll
-want to use the Bazaar ``merge-package`` command rather than just ``merge``::
+trunk are large and you feel should be tested along with your change you can
+merge them into your bug fix branch and test there.  If not,
+then you can carry on merging your bug fix branch into the development trunk
+branch. You'll want to use the Bazaar ``merge-package`` command rather than just
+``merge``::
 
     $ bzr merge-package ../bug-12345
 
@@ -41,26 +42,18 @@
 before you upload the source package.
 
 The next step is to build and test the modified source package as you normally
-would.  Once you are happy with the upload then you should `dput` the
-source package.  For example, if you want to upload your changes to your PPA,
-then you'd do::
-
-    $ dput ppa:imasponsor/myppa tomboy_1.5.2-1ubuntu5_source.changes
-
-or, if you have permission to upload to the primary archive::
-
-    $ dput tomboy_1.5.2-1ubuntu5_source.changes
-
-You might want to do one more `debcommit` to make sure all your changes are
-committed in your working tree.
+would::
+
+    $ bzr bd -S
 
 The last step is to mark the change as being the same as the source package
-that was uploaded, so run::
-
-    $ bzr mark-uploaded
-
-This also tells the package importer that what is in the Bazaar branch is the
-same as in the archive.
+that was uploaded, bzr-builddeb will override the `tag` command to
+automatically tag with the version number in debian/changelog so run::
+
+    $ bzr tag
+
+This tag will tell the package importer that what is in the Bazaar branch
+is the same as in the archive.
 
 Now you can push the changes back to Launchpad::
 
@@ -68,6 +61,16 @@
 
 (Change the destination if you are uploading an SRU or similar.)
 
+Once you are happy with the upload then you should use `dput` to upload the
+built source package to Launchpad. For example, if you want to upload your
+changes to your PPA, then you'd do::
+
+    $ dput ppa:imasponsor/myppa tomboy_1.5.2-1ubuntu5_source.changes
+
+or, if you have permission to upload to the primary archive::
+
+    $ dput ubuntu tomboy_1.5.2-1ubuntu5_source.changes
+
 You are now free to delete your feature branch, as it is merged, and can
 be re-downloaded from Launchpad if needed.
 
 
=== modified file 'udd-working.rst'
--- udd-working.rst	2011-02-05 01:02:31 +0000
+++ udd-working.rst	2011-07-15 09:23:07 +0000
@@ -1,6 +1,6 @@
-====================
-Working on a Package
-====================
+=====================================================
+Ubuntu Distributed Development - Working on a Package
+=====================================================
 
 Once you have the source package branch in a shared repository, you'll want to
 create additional branches for the fixes or other work you plan to do.  You'll
@@ -15,7 +15,7 @@
 The first thing to do is to make sure your source package branch is
 up-to-date.  It will be if you just checked it out, otherwise do this::
 
-    $ cd natty
+    $ cd tomboy.dev
     $ bzr pull
 
 Any updates to the package that have uploaded since your checkout will now be
@@ -25,7 +25,7 @@
 repository you previously created for Tomboy, you can create your bug fix
 branch like this::
 
-    $ bzr branch natty bug-12345
+    $ bzr branch tomboy.dev bug-12345
     $ cd bug-12345
 
 Now you can do all my work in the `bug-12345` directory.  You make changes
@@ -41,9 +41,8 @@
 
 .. _link-via-changelog:
 
-Here's where things diverge a little from typical Bazaar usage.  When you
-added your `debian/changelog` entry, you should have included a bug fix tag
-that indicated which Launchpad bug issue you're fixing.  The format of this
+When you added your `debian/changelog` entry, you should have included a bug fix
+tag that indicated which Launchpad bug issue you're fixing.  The format of this
 textual tag is pretty strict: ``LP: #12345``.  The space between the ``:`` and
 the ``#`` is required and of course the number will be replaced by the actual
 bug number you're fixing.  Your `debian/changelog` entry might look something
@@ -55,18 +54,15 @@
 
      -- Bob Dobbs <[e-mail]>  Mon, 10 Jan 2011 16:10:01 -0500
 
-Normally, when you want to commit changes to your branch, you just use ``bzr
-commit``, but in the case where you've made a change to ``debian/changelog``,
-you'll want to use the ``debcommit`` command instead::
-
-    $ debcommit
-
-The reason to use ``debcommit`` instead is that it automatically includes your
-``debian/changelog`` entry in the commit message, and it also adds the
-necessary metadata to link your branch to the bug report when you push your
-branch to Launchpad.  You can do that manually with ``bzr commit`` (and
-eventually, ``bzr commit`` may get smart enough to do it for you), but for now
-``debcommit`` is the most convenient way to do it.
+Commit with the normal::
+
+    bzr commit
+
+A hook in bzr-builddeb will use the debian/changelog text as the commit
+message and set the tag to mark bug #12345 as fixed.
+
+This only works with bzr-builddeb 2.7.5 and bzr 2.4, for older versions use
+`debcommit`.
 
 
 Building the package
@@ -95,16 +91,5 @@
 Note that while `bzr bd` has a `--native` switch, it does not have a
 `--no-native` switch.
 
-You might also see an error that looks something like this:
-
-    dpkg-source: error: Version number suggests Ubuntu changes, but
-    Maintainer: does not have Ubuntu address
-
-In a sense, this is a safeguard to ensure that ``update-maintainer`` is run
-when necessary.  However in this case, you can just temporarily set the
-``$DEBEMAIL`` environment variable to a [e-mail] address::
-
-    $ DEBEMAIL='[e-mail]' bzr bd -S
-
 Once you've got the source package, you can build it as normal with
-``pbuilder`` or ``sbuild``.
+``pbuilder-dist`` (or ``pbuilder`` or ``sbuild``).