ubuntu-packaging-guide-team team mailing list archive

[Barry Warsaw <barry@xxxxxxxxxxxxx>]

Barry Warsaw has proposed merging lp:~barry/ubuntu-packaging-guide/udd-update into lp:ubuntu-packaging-guide.

Requested reviews:
  Ubuntu Packaging Guide Team (ubuntu-packaging-guide-team)

For more details, see:
https://code.launchpad.net/~barry/ubuntu-packaging-guide/udd-update/+merge/90976

- Fixes lots of typos and formatting issues.
- Updates merge commands now that `bzr merge` can be used instead of `bzr
  merge-package` (as of Precise)
- Get rid of all the discussion of using looms to develop patches.  It doesn't
  seem to work right anymore and it's complicated and confusing.
-- 
https://code.launchpad.net/~barry/ubuntu-packaging-guide/udd-update/+merge/90976
Your team Ubuntu Packaging Guide Team is requested to review the proposed merge of lp:~barry/ubuntu-packaging-guide/udd-update into lp:ubuntu-packaging-guide.

=== modified file 'udd-getting-the-source.rst'
--- udd-getting-the-source.rst	2011-10-03 13:21:40 +0000
+++ udd-getting-the-source.rst	2012-01-31 23:09:26 +0000
@@ -30,7 +30,7 @@
 
 You can use a similar scheme to access the source branches in Debian, although
 there are no shortcuts for the Debian distro-series names.  To access the
-Tomboy branch in the current development series for Debian use:
+Tomboy branch in the current development series for Debian use::
 
     debianlp:tomboy
 
@@ -96,11 +96,20 @@
 Ensuring the version is up to date
 ----------------------------------
 
-When you do your ``bzr branch`` you will get a message telling you if the packaging branch is up to date.  Occationally the importer fails and packaging branches do not match what is in the archive.  A message saying::
+When you do your ``bzr branch`` you will get a message telling you if the
+packaging branch is up to date.  For example::
+
+    $ bzr branch ubuntu:tomboy
+    Most recent Ubuntu version: 1.8.0-1ubuntu1.2
+    Packaging branch status: CURRENT
+    Branched 86 revisions.
+
+Occasionally the importer fails and packaging branches do not match what is in
+the archive.  A message saying::
 
     Packaging branch status: OUT-OF-DATE
 
-Means the importer has failed.  You can find out why on
+means the importer has failed.  You can find out why on
 http://package-import.ubuntu.com/status/ and `file a bug on the UDD
 project`_ to get the issue resolved.
 
@@ -112,11 +121,11 @@
 
     bzr get-orig-source
 
-The works from bzr-builddeb version 2.7.10.  It will try a number of methods to
-get the upstream tar, firstly by recreating it from the ``upstream-x.y`` tag in
-the bzr archive, then by downloading from the ubuntu archive, lastly by running
-``debian/rules get-orig-source``. The upstream tar will also be recreated when
-using bzr to build the package::
+This will try a number of methods to get the upstream tar, firstly by
+recreating it from the ``upstream-x.y`` tag in the bzr archive, then by
+downloading from the Ubuntu archive, lastly by running ``debian/rules
+get-orig-source``. The upstream tar will also be recreated when using bzr to
+build the package::
 
     bzr builddeb
 

=== modified file 'udd-latest.rst'
--- udd-latest.rst	2011-07-13 14:44:16 +0000
+++ udd-latest.rst	2012-01-31 23:09:26 +0000
@@ -2,8 +2,8 @@
 Getting The Latest
 ==================
 
-If someone else has landed changes on a package, you will want to pull down
-those changes in your own copies of the package branches.
+If someone else has landed changes on a package, you will want to pull those
+changes in your own copies of the package branches.
 
 
 Updating your main branch
@@ -35,15 +35,15 @@
 the harder may be, so doing it regularly should keep each merge simple.  Even
 if there are many merges the total effort would hopefully be less.
 
-To merge the changes you just need to use `bzr merge-package`, but you must
+To merge the changes you just need to use ``bzr merge``, but you must
 have committed your current work first::
 
     $ cd tomboy/bug-12345
-    $ bzr merge-package ../tomboy.dev
+    $ bzr merge ../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
-revert`.  Once you are happy with the changes then use `bzr commit`.
+changes that you just merged use ``bzr diff``.  To undo the merge use ``bzr
+revert``.  Once you are happy with the changes then use ``bzr commit``.
 
 
 Referring to versions of a package

=== modified file 'udd-merging.rst'
--- udd-merging.rst	2011-10-19 17:41:59 +0000
+++ udd-merging.rst	2012-01-31 23:09:26 +0000
@@ -5,10 +5,10 @@
 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,
 and from other Ubuntu developers.  Doing it in Bazaar is pretty simple, and
-all based around the `bzr merge-package` command.
+all based around the ``bzr merge`` command.
 
 When you are in any branch's working directory then you can merge from
-another.  First check you have no uncommitted changes::
+another.  First check that you have no uncommitted changes::
 
     $ bzr status
 
@@ -19,20 +19,21 @@
 Merging from Debian
 ===================
 
-Next run `bzr merge-package` passing the URL of the branch to merge from.  For
-instance, to merge from the version of the package in Debian Squeeze_ run::
+Next run ``bzr merge`` passing the URL of the branch to merge from.  For
+example, to merge from the version of the package in Debian Squeeze_ run::
 
-    $ bzr merge-package lp:debian/squeeze/tomboy
+    $ bzr merge debianlp:squeeze/tomboy
 
 This will merge the changes since the last merge point and leave you with
 changes to review.  This may cause some conflicts.  You can see everything
-that the `merge-package` command did by running::
+that the ``merge`` command did by running::
 
     $ bzr status
     $ bzr diff
 
 If conflicts are reported then you need to edit those files to make them look
-how they should, removing the *conflict markers*.  Once you have done, run::
+how they should, removing the *conflict markers*.  Once you have done this,
+run::
 
     $ bzr resolve
     $ bzr conflicts
@@ -53,9 +54,9 @@
 
     $ bzr diff -r tag:0.6.10-5
 
-which will show the diff between the new Debian (0.6.10-5) and Ubuntu versions
-(0.6.10-5ubuntu1).  In similar way you can compare to any other versions.  To
-see all available versions run::
+which will show the differences between the Debian (0.6.10-5) and Ubuntu
+versions (0.6.10-5ubuntu1).  In similar way you can compare to any other
+versions.  To see all available versions run::
 
     $ bzr tags
 
@@ -65,9 +66,9 @@
 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
-``_source.changes`` file.   For example::
+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 builddeb -S --package-merge
 
@@ -78,35 +79,35 @@
 When upstream releases a new version (or you want to package a snapshot), you
 have to merge a tarball into your branch.
 
-This is done using the `bzr merge-upstream` command.  If your package has a
-valid `debian/watch` file, from inside the branch that you want to merge to,
+This is done using the ``bzr merge-upstream`` command.  If your package has a
+valid ``debian/watch`` file, from inside the branch that you want to merge to,
 just type this::
 
     $ bzr merge-upstream
 
 This will download the tarball and merge it into your branch, automatically
-adding a `debian/changelog` entry for you.  `bzr-builddeb` looks at the
-`debian/watch` file for the upstream tarball location.
+adding a ``debian/changelog`` entry for you.  ``bzr-builddeb`` looks at the
+``debian/watch`` file for the upstream tarball location.
 
-If you do *not* have a `debian/watch` file, you'll need to specify the location
-of the upstream tarball, and the version manually::
+If you do *not* have a ``debian/watch`` file, you'll need to specify the
+location of the upstream tarball, and the version manually::
 
     $ bzr merge-upstream --version 1.2 http://example.org/releases/foo-1.2.tar.gz
 
-The `--version` option is used to specify the upstream version that is being
+The ``--version`` option is used to specify the upstream version that is being
 merged in, as the command isn't able to infer that (yet).
 
 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.  The
-tarball will be renamed appropriately and, if required, converted to .gz.
+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
 review the changes before committing as normal.
 
 If you are merging an upstream release into an existing Bazaar branch that has
-not previously used the UDD layout, `bzr merge-upstream` will fail with an
+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 repository for the last

=== modified file 'udd-newpackage.rst'
--- udd-newpackage.rst	2011-10-19 17:41:59 +0000
+++ udd-newpackage.rst	2012-01-31 23:09:26 +0000
@@ -13,8 +13,7 @@
 
 I started with a Python library called `flufl.enum`_, which is a fairly
 typical setuptools-based Python package.  Fortunately, it's also maintained in
-Launchpad using Bazaar, so that makes bootstrapping much easier.  (TBD: add
-instructions for using other upstream VCSs.)
+Launchpad using Bazaar, so that makes bootstrapping much easier.
 
 Because we want to package the trunk branch, getting started is pretty
 simple::
@@ -31,11 +30,11 @@
 Bootstrapping
 =============
 
-You need to create the initial ``debian`` directory, as well as the necessary 
-files inside the ``debian`` directory.  Currently, there are many ways to set up 
-this directory, but hopefully there will be `some convergence`_ in the methods,
-especially if you're building standard Python setuptools-based libraries and
-applications.
+You need to create the initial ``debian`` directory, as well as the necessary
+files inside the ``debian`` directory.  Currently, there are many ways to set
+up this directory, but hopefully there will be `some convergence`_ in the
+methods, especially if you're building standard Python setuptools-based
+libraries and applications.
 
 .. COMMENT  Is "Bootstrapping" the technical / commonly-used developer term? Also, please list the files needed in the debian directory.
   
@@ -43,11 +42,9 @@
 The bzr-builddeb way
 --------------------
 
-.. This section seems a bit too casual, and assumes to much prior knowledge (re: use of "of course").
-
-You could of course just use `dh_make(8)` to get things going, or you could
-use `bzr dh-make`.  The latter might provide some benefits, and can be run
-like so from inside your branch::
+You could use the `dh_make` command to get things going, or similiarly the
+`bzr dh-make`.  The latter might provide some benefits, and can be run like so
+from inside your branch::
 
     $ bzr dh-make PKGNAME VERSION DOWNLOADURL
     $ bzr add debian
@@ -65,8 +62,8 @@
 The stdeb way
 -------------
 
-Another way I've found useful for initializing the ``debian`` directory for
-Python setuptools-based packages, is to use the stdeb_ package.  The full
+Another way for creating the initial ``debian`` directory for Python
+setuptools-based packages, is to use the stdeb_ package.  The full
 documentation for this package is available on the `upstream home`_, but you
 won't need all of the commands.  stdeb has a command that is *exactly* what
 we're looking for!

=== modified file 'udd-patchsys.rst'
--- udd-patchsys.rst	2011-07-25 13:19:56 +0000
+++ udd-patchsys.rst	2012-01-31 23:09:26 +0000
@@ -1,11 +1,6 @@
-==============================================================
-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.
+======================
+ Working with Patches
+======================
 
 Many existing packages that have changes from upstream express those changes
 using a patch system, of which there are several to choose from.  Usually,
@@ -17,91 +12,129 @@
 your package has a patch system by using the ``what-patch`` command (from the
 ``ubuntu-dev-tools`` package).
 
-Although UDD, and in particular `Bazaar looms`_ makes it pretty easy to keep
-individual patches separated, if you're submitting changes to be uploaded,
-you're currently better off playing along with the package's patch system.
-*You will want at least bzr loom version 2.2.1dev, otherwise you'll have
-problems pushing and pulling your threads to Launchpad.* Do ``bzr plugins`` to
-find the version you're using.
-
-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.
-You do not need to ``quilt push -a`` manually, and in fact, you'll get a tree
-with lots of distracting modifications if you push or pop all the changes.  Or
-to put it another way, once you have a branch, jump right in!
+While Debian has several patch systems, Quilt_ is becoming the most popular.
+Quilt acts something like a version control system itself, and in the context
+of UDD, this can be both a good thing and a bad thing.  With Bazaar 2.5 and
+``bzr-builddeb`` 2.8.1 (in Ubuntu 12.04 Precise), handling source packages
+with quilt patches has become much easier.
+
+There are two main tasks where you'll have to be aware of quilt patches, when
+developing your own patch to the upstream code, and when merging new versions
+of the package from Debian where either the Debian or Ubuntu (or both) have
+quilt patches in the source branch.
+
+Here are some guidelines for working with quilt patches in UDD in these two
+scenarios.  Some of these techniques are works-in-progress, so you should
+adapt them to your own workflow, and keep watching for improvements from the
+Bazaar teams.
+
+
+Patches are applied in source branches
+======================================
+
+One important thing to keep in mind: all source branches reflect the tree
+after a ``quilt push -a``.  In other words, when you branch a source branch
+from Launchpad, you get the tree with all patches applied, ready for you to
+jump right into hacking.  You do not need to ``quilt push -a`` manually, and
+in fact, you'll get a tree with lots of distracting modifications if you push
+or pop all the changes.  Or to put it another way, once you have a branch,
+jump right in!
+
+
+Merging from Debian with quilt patches
+======================================
+
+With newer versions of Bazaar as mentioned above, merging new Debian versions
+to Ubuntu versions should be quite easy now, even when one or both packages
+have quilt patches.  Just use ``bzr merge`` as you normally would.  Under the
+hood, Bazaar will first unapply all the patches, then do the merge, then if
+there are no conflicts, it will re-apply the patches leaving you again with a
+source branch in the ``quilt push -a`` state.
+
+For example, if we want to merge the Debian version of the ``aptitude``
+package with the Ubuntu version, we would do something like this::
+
+    $ bzr init-repo aptitude
+    $ cd aptitude
+    $ bzr branch ubuntu:aptitude precise
+    $ bzr branch debianlp:aptitude wheezy
+    $ cd precise
+    $ bzr merge ../wheezy
+
+If there are merge conflicts, the quilt patches will remain unapplied so that
+you can resolve the conflicts more easily.  You would use a combination of bzr
+and quilt commands to resolve the conflicts, until all the quilt patches are
+applied again.  Then you're ready to commit, push, and build as you normally
+would.
 
 
 Develop your patch
 ==================
 
-Start as you normally would with UDD and looms::
-
-    $ bzr init-repo foobar
-    $ cd foobar
-    $ bzr branch ubuntu:foobar
-    $ bzr branch foobar bug-12345
+There is a strong preference to fixing packages using a patch system like
+quilt, rather than modifying the source code directly.  This is because with a
+patch system, it's easier to communicate those changes to Debian or upstream
+(where UDD isn't used), and to remove patches when upstream fixes the bug the
+patch addresses (possibly in a completely different way).
+
+Let's say there's a bug in the ``dbus`` package that you want to fix.  You
+start the way you normally would with any package in UDD::
+
+    $ bzr init-repo dbus
+    $ cd dbus
+    $ bzr branch ubuntu:dbus precise
+    $ bzr branch precise bug-12345
     $ cd bug-12345
-    $ bzr loomify --base trunk
-    $ bzr create-thread sourcefix
-
-Now that you are in the ``sourcefix`` thread, just edit the source code,
-making whatever changes you need to fix the bug.  Don't worry about the patch
-system at this point, at least until you are happy with your changes.  If
-someone else pushes changes to the package while you're working on it, just
-``bzr commit`` your current work, ``bzr down-thread`` to ``trunk``, pull the
-updates, and ``bzr up-thread --auto`` back to the ``sourcefix`` thread,
-resolving any conflicts along the way.  You can periodically commit your
-changes, ``bzr record`` and push them to Launchpad as you go, of course
-linking your branch to the bug in Launchpad.  So far, it's just normal
-development with looms.
-
-Once you're happy with your changes, you need to essentially import your
-thread's changes into a quilt patch.  This is fairly easy to do.  While inside
-the ``sourcefix`` thread do::
-
-    $ bzr create-thread quiltfix
-    $ bzr diff -rthread:trunk..thread:sourcefix | quilt import -p0 -P bug-12345 /dev/stdin
-    $ bzr add debian/patches/bug-12345
-    $ quilt push
-    $ quilt pop
-    $ bzr commit
-
-Why the last push/pop before the commit?  The push gets the imported changes
-into the quilt patch, but also leaves the tree modified, so you'll essentially
-have the changes both in the ``debian/`` directory and in the source tree.
-The pop undoes the tree changes (which are also available in the ``sourcefix``
-thread), but leaves the quilt change available.  A ``bzr commit`` at this
-point gives you a thread with just the changes to ``debian/``.
-
-
-Problems
-========
-
-The problem comes when you want to modify the patch, e.g.::
-
-    $ bzr down-thread
-    <hack, commit>
-
-This does *not* work well::
-
-    $ bzr up-thread
-
-You'd expect at this point to be able to ``quilt fold`` your new changes to
-update your ``bug-12345`` quilt patch, but in fact, this doesn't work.  You can
-end up with difficult to resolve conflicts, patch failures and rejections.  My
-recommendation is that when you make changes to your ``sourcefix`` thread,
-blow away your ``quiltfix`` thread and regenerate it.  Looms make this easy::
-
-    $ bzr up-thread
-    $ bzr revert
-    $ bzr combine-thread --force (throws away your quiltfix changes)
-    $ bzr create-thread quiltfix
-    $ bzr diff -rthread:trunk..thread:sourcefix | quilt import -p0 -P bug-12345 /dev/stdin
-    etc...
-
-So you've thrown away the original ``quiltfix`` thread and recreated it, with
-your updated ``sourcefix`` changes.
+
+Maybe the bug is pretty simple; there's a typo in the ``README`` file.  Just
+fix the typo in your favorite editor, then do a ``bzr stat`` to prove that the
+file has been edited::
+
+    $ bzr stat
+    modified:
+      README
+
+Now, in order to get this fix into a quilt patch, we need to generate a diff,
+but we need the resulting patch to have a format that is consumable by quilt.
+The way to do that is to use the ``--prefix`` (or ``-p``) option to ``bzr
+diff``::
+
+    $ bzr diff -p "a/:b/" > ../bug-12345.patch
+
+What this actually does is to produce a *level 1* diff, which is required by
+the quilt command we're going to use below.  Normally, ``bzr diff`` produces
+*level 0* diffs which are more easily read by humans, but this won't work with
+quilt (despite the implication in the quilt documentation).
+
+The above command generates the patch and stores it in a file one level up
+from the working tree.  Note that here we're using the ``a`` and ``b``
+directory prefixes for the diff, but the actual names don't really matter.
+
+Now all you need to do is to import the patch into your quilt patches.  If you
+named the file above with the same name you want into your quilt stack, then
+just do this::
+
+    $ quilt import ../bug-12345.patch
+    $ bzr add debian/patches/bug-12345.patch
+
+You need the last line to inform Bazaar about the new quilt patch file.  You
+can see that the quilt patch's name is the same as the file name you generated
+above.  Of course, you can change this by using the ``-P`` option to ``quilt
+import``.
+
+One important thing to notice is that if you do the commands ``bzr stat`` and
+a ``quilt applied`` , you'll see that the ``README`` file is still modified,
+but the ``bug-12345.patch`` is not yet applied.  If you try to apply the newly
+imported quilt patch (with ``quilt push``), it will fail because you're
+applying a patch on top of the already patched file.
+
+One way around this is to revert the change to ``README`` before doing the
+``quilt push``.  However, if you think you may want to continue to develop the
+patch, and thus do not want to throw away your in-tree changes, use ``bzr
+shelve`` to save the change in the working tree to the side, then do ``quilt
+push``.  Either way, once you've pushed your top quilt patch, you can just
+edit the tree in place, and do ``quilt refresh`` commands to update the top
+quilt patch.
 
 
 Gotchas
@@ -119,36 +152,6 @@
 directory in your branch.
 
 
-Publishing your changes
-=======================
-
-It's actually easier at this point to generate a diff for attaching to the bug
-report.  While inside the ``quiltfix`` thread, just::
-
-    $ bzr up-thread --auto
-    $ bzr diff -rthread: > bug-12345.diff
-
-The differences between the ``quiltfix`` thread and the ``sourcefix`` thread
-are the interesting bits, and totally appropriate for committing and upload.
-Because of the way looms interacts with Launchpad, you can still link your
-branch to the bug and request a merge proposal, but understand that the diff
-will include all changes between ``quiltfix`` (top) and ``trunk`` (bottom)
-threads.  So the merge proposal will include the changes in the ``debian/``
-directory, *and* the changes in the source tree.  As long as you and your
-reviewer understands this, you should be okay, but it can be confusing at
-first.
-
-If you need a sponsor to merge and upload your changes, one thing they *do
-not* want to do is::
-
-    $ bzr branch ubuntu:foobar
-    $ cd foobar
-    $ bzr merge lp:~you/ubuntu/natty/foobar/yourfix
-
-Much badness (in the form of infinite *maximum recursion depth* exceptions)
-ensues.  Yes, we need to file a bug on that.
-
-
 edit-patch
 ==========
 
@@ -162,28 +165,15 @@
   * By default, ``bzr diff`` produces a ``-p0`` patch, but ``edit-patch``
     defers to the underlying patch system's default.  For quilt, this is
     ``-p1``.  ``quilt import`` takes a ``-p`` argument to specify the prefix
-    level, but this isn't yet exposed in ``edit-patch``.  If you're
-    adventurous, try changing the ``bzr diff`` command above to specify the
-    proper prefixes using its ``-p`` option.
+    level, but this isn't yet exposed in ``edit-patch``.  If you use the
+    ``--prefix`` argument to the ``bzr diff`` command as shown above, you
+    should be okay.
   * By default, ``edit-patch`` requires a path to an existing patch file, but
     it's more convenient to pipe the output of ``bzr diff`` to the stdin of
     ``edit-patch``, as shown above.  The alternative would be to save the diff
     in a temporary file, and then point ``edit-patch`` to this temporary file.
 
 
-Future
-======
-
-Ideally, it would be nice to add a ``bzr edit-patch`` or some such command
-which does the whole loom -> patch system import.  At least ``edit-patch``
-could grow a ``-p`` and ``-P`` option, as well as read from stdin.  Stay
-tuned, or get involved!
-
-There's now `a bug` that tracks this.
-
-
-.. _`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
 .. _`a different patch system`: http://wiki.debian.org/debian/patches
-.. _`a bug`: https://launchpad.net/bugs/620721

=== modified file 'udd-sponsorship.rst'
--- udd-sponsorship.rst	2011-07-25 13:19:56 +0000
+++ udd-sponsorship.rst	2012-01-31 23:09:26 +0000
@@ -1,6 +1,6 @@
-===============================================================
-Seeking Review and Sponsorship
-===============================================================
+================================
+ 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
@@ -44,7 +44,7 @@
 
     $ bzr lp-open
 
-if that fails, then you can use
+If that fails, then you can use::
 
     $ xdg-open https://code.launchpad.net/~subgenius/ubuntu/natty/tomboy/bug-12345
 
@@ -71,8 +71,8 @@
 Another way is to is to open the merge proposal and download the diff.
 
 You should ensure that diff has the changes you expect, no more and no less.
-Name the diff appropriately, e.g. foobar-12345.debdiff and attach it to the
-bug report.
+Name the diff appropriately, e.g. ``foobar-12345.debdiff`` and attach it to
+the bug report.
 
 
 Dealing with feedback from sponsors
@@ -85,14 +85,14 @@
     $ bzr commit
 
 Now when you push your branch to Launchpad, Bazaar will remembered where you
-pushed to, and will only update the branch on Launchpad with your latest
-commits.  All you need to do is::
+pushed to, and will update the branch on Launchpad with your latest commits.
+All you need to do is::
 
     $ bzr push
 
-You can then reply to the merge proposal review explaining what you changed,
-and asking for re-review, or you can reply on the merge proposal page in
-Launchpad.
+You can then reply to the merge proposal review email explaining what you
+changed, and asking for re-review, or you can reply on the merge proposal page
+in Launchpad.
 
 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

=== modified file 'udd-uploading.rst'
--- udd-uploading.rst	2011-10-19 17:41:59 +0000
+++ udd-uploading.rst	2012-01-31 23:09:26 +0000
@@ -24,31 +24,35 @@
 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 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``::
+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.  As of
+bzr 2.5 and bzr-builddeb 2.8.1, this works with just the standard ``merge``
+command::
+
+    $ bzr merge ../bug-12345
+
+For older versions of bzr, you can use the ``merge-package`` command instead::
 
     $ bzr merge-package ../bug-12345
 
 This will merge the two trees, possibly producing conflicts, which you'll need
 to resolve manually.
 
-Next you should make sure the `debian/changelog` is as you would like, with
+Next you should make sure the ``debian/changelog`` is as you would like, with
 the correct distribution, version number, etc.
 
-Once that is done you should review the change you are about to commit
-with `bzr diff`.  This should show you the same changes as a debdiff would
-before you upload the source package.
+Once that is done you should review the change you are about to commit with
+``bzr diff``.  This should show you the same changes as a debdiff would before
+you upload the source package.
 
 The next step is to build and test the modified source package as you normally
 would::
 
     $ bzr builddeb -S
 
-The last step is to mark the change as being the same as the source package
-that was uploaded, bzr-builddeb will override the `tag` command to
-automatically tag with the version number in debian/changelog so run::
+When you're finally happy with your branch, make sure you've committed all
+your changes, then tag the branch with the changelog's version number.  The
+``bzr tag`` command will do this for you automatically::
 
     $ bzr tag
 
@@ -61,15 +65,15 @@
 
 (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::
+You need one last step to get your changes uploaded into Ubuntu or your PPA;
+you need to ``dput`` the source package to the appropriate location.  For
+example, if you want to upload your changes to your PPA, 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
+    $ dput 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.
@@ -82,7 +86,7 @@
 of merging from a branch you created, you merge from the branch in the merge
 proposal::
 
-    $ bzr merge-package lp:~subgenius/ubuntu/natty/tomboy/bug-12345
+    $ bzr merge lp:~subgenius/ubuntu/natty/tomboy/bug-12345
 
 If there are lots of merge conflicts you would probably want to ask the 
 contributor to fix them up.  See the next section to learn how to cancel
@@ -91,7 +95,7 @@
 But if the changes look good, commit and then follow the rest of the uploading
 process::
 
-    $ bzr commit --author Bob Dobbs <subgenius@xxxxxxxxxxx>
+    $ bzr commit --author "Bob Dobbs <subgenius@xxxxxxxxxxx>"
 
 
 Canceling an upload
@@ -114,9 +118,9 @@
 branch first.
 
 If you already have a branch where you are working on the package and you
-would like to include their changes, then simply run the `bzr merge-package`
-from that branch, instead of the checkout of the development package.  You can
-then make the changes and commit, and then carry on with your changes to the
+would like to include their changes, then simply run the ``bzr merge`` from
+that branch, instead of the checkout of the development package.  You can then
+make the changes and commit, and then carry on with your changes to the
 package.
 
 If you don't have an existing branch, but you know you would like to make

=== modified file 'udd-working.rst'
--- udd-working.rst	2011-10-19 17:41:59 +0000
+++ udd-working.rst	2012-01-31 23:09:26 +0000
@@ -1,6 +1,6 @@
-=====================================================
-Working on a Package
-=====================================================
+======================
+ 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
@@ -41,11 +41,11 @@
 
 .. _link-via-changelog:
 
-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
+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 you should use the actual bug
+number that you're fixing.  Your `debian/changelog` entry might look something
 like::
 
     tomboy (1.5.2-1ubuntu5) natty; urgency=low
@@ -92,4 +92,6 @@
 `--no-native` switch.
 
 Once you've got the source package, you can build it as normal with
-``pbuilder-dist`` (or ``pbuilder`` or ``sbuild``).
+``pbuilder-dist`` (or ``pbuilder`` or `sbuild`_).
+
+.. _`sbuild`: https://wiki.ubuntu.com/SecurityTeam/BuildEnvironment