Merge lp:~jr/ubuntu-packaging-guide/03-packaging-from-scratch into lp:ubuntu-packaging-guide

[Jonathan Riddell]

Add a packaging from scratch guide

[Barry Warsaw (barry)]

Question for Daniel: British English or American English?

[Barry Warsaw (barry)]

s/check it compiles/check that it compiles/

Line 74 "A running programme..." doesn't make sense to me (seems out of place or incomplete).

I personally would like to promote pkgme over `bzr dh-make` as I think the former is a better overall framework for helping people get the packaging basics added. It's also much simpler, and doesn't ask the user to answer difficult questions. Can you check to see if pkgme does the right thing for your example, and if so, switch to that?

(The downside is that pkgme itself isn't in the archives, but it can be installed from a PPA. It's also less mature than dh-make, but that doesn't seem to be too big a negative for UDD, so we might as well be opinionated here too ;).

line 102 doesn't parse for me: +``compat`` tell the ``debhelper`` scripts which build the package what version
103 +to run as. Ensure it says ``7``.

meta data, or metadata?

How about instead of "Even if it builds the .deb binary package, your packaging will not yet be a work
158 +of perfection, nothing is first time."

"Even if the .deb binary package was built correctly, your package may still have bugs."

Should you also recommend uploading the package to a PPA? There are a few things that happen on the LP buildds that normally don't happen on a local build, so the PPA is as close to "reality" as you can get without actually uploading to the archive.

review: Needs Information

[lp:~jr/ubuntu-packaging-guide/03-packaging-from-scratch]

69. By Jonathan Riddell on 2011-07-18

merge in trunk

70. By Jonathan Riddell on 2011-07-18

improve compat description

71. By Jonathan Riddell on 2011-07-18

be consistent about 'metadata'

72. By Jonathan Riddell on 2011-07-18

nicer wording

[Jonathan Riddell (jr)]

All done except pkgme. I haven't found any information on how to use pkgme and it just complains about no backend when I run it for this package.

[lp:~jr/ubuntu-packaging-guide/03-packaging-from-scratch]

73. By Jonathan Riddell on 2011-07-18

upload to PPA

[Barry Warsaw (barry)]

Currently, you have to run pkgme from its PPA.

[Barry Warsaw (barry)]

1. The section on fixing a security bug breaks out of the UDD track to use apt-get source. If possible though I think you can use an ubuntu:<series>/<package> url though, right? E.g. ubuntu:lucid/tomboy.

2. Also, s/may will/may/ in packaging-from-scratch.rst

Still setting to Needs Fixing to get your feedback on issue #1.

review: Needs Fixing

[Jonathan Riddell (jr)]

1. There's nothing about security bugs in this merge proposal, there was a chapter added on that recently by others.

2. done

[lp:~jr/ubuntu-packaging-guide/03-packaging-from-scratch]

74. By Jonathan Riddell on 2011-07-19

grammer fix

75. By Jonathan Riddell on 2011-07-20

merge in trunk

Unmerged revisions

=== added file 'images/kdetoys-udd-branch.png'
Binary files images/kdetoys-udd-branch.png	1970-01-01 00:00:00 +0000 and images/kdetoys-udd-branch.png	2011-07-20 11:01:36 +0000 differ
=== added file 'images/kdetoys-udd-diff.png'
Binary files images/kdetoys-udd-diff.png	1970-01-01 00:00:00 +0000 and images/kdetoys-udd-diff.png	2011-07-20 11:01:36 +0000 differ
=== modified file 'index.rst'
--- index.rst	2011-07-19 13:13:58 +0000
+++ index.rst	2011-07-20 11:01:36 +0000
@@ -9,8 +9,14 @@
 The guide is split up into two sections:
 
 * A list of articles based on tasks, things you want to get done.
-* A set of articles that dig deeper into specific bits of our tools
-  and workflows.
+* A set of knowledge-base articles that dig deeper 
+  into specific bits of our tools and workflows.
+
+This guide focuses on the Ubuntu Distributed Development packaging method. 
+This is a new way of packaging which uses Distributed Revision Control
+branches.  It currently has some limitations which mean many teams in Ubuntu
+use :doc:`traditional packaging</traditional-packaging>` methods.  See the
+:doc:`UDD Introduction</udd-intro>` page for an introduction to the differences.
 
 Articles
 --------
@@ -20,6 +26,8 @@
 
    introduction-to-ubuntu-development
    getting-set-up
+   udd-intro
+   packaging-from-scratch
    fixing-a-bug
    fixing-a-bug-security
 
@@ -31,7 +39,7 @@
 
    debian-dir-overview
    testing
-   udd-intro
+   udd-getting-the-source
    udd-working
    udd-sponsorship
    udd-uploading
@@ -39,6 +47,7 @@
    udd-merging
    udd-patchsys
    udd-newpackage
+   traditional-packaging
 
 
 Indices and tables

=== added file 'packaging-from-scratch.rst'
--- packaging-from-scratch.rst	1970-01-01 00:00:00 +0000
+++ packaging-from-scratch.rst	2011-07-20 11:01:36 +0000
@@ -0,0 +1,199 @@
+======================
+Packaging From Scratch
+======================
+
+You have found an exciting new piece of software, it needs exposure to the
+wider world by getting it into Ubuntu or a PPA, so you have decided to package
+it.
+
+Checking the Programme
+----------------------
+
+The first stage in packaging is to get the released tar from upstream (we call
+the authors of applications "upstream") and check that it compiles and runs.
+
+This guide will take you through packaging a simple application called KQRCode
+which has been `posted on KDE-apps.org`_.  Download `version 0.4 from
+Sourceforge`_ and put it in a new directory.
+
+Now uncompress it::
+
+    $ tar xf kqrcode-0.4.tar.gz
+    $ cd kqrcode-0.4
+
+This application uses the CMake build system so we want to run cmake to prepare
+for compilation::
+
+    $ mkdir build
+    $ cd build
+    $ cmake ..
+
+CMake will check for the required dependencies, in this case it tells us we
+need Qt and KDE libraries.  We also need GCC, packagers can install
+``build-essential`` which brings this in and is assumed to be installed for all
+packages. If you do not have the development files for these libraries installed
+it will fail, you can install them and run CMake again::
+
+    $ sudo apt-get install build-essential libqt4-dev kdelibs5-dev
+    $ cmake ..
+
+Now you can compile the source::
+
+    $ make
+
+Running this gives some errors about missing headers.  This means there are
+other libraries missing which were not checked by CMake.  Make a note to inform
+upstream of this problem.  `packages.ubuntu.com`_ can be used to find which
+packages these headers come from, install these packages and continue the
+compile::
+
+    $ sudo apt-get install libqrencode-dev libzbar-dev libzbarqt-dev
+    $ make
+
+If the compile completes successfully you can install and run the programme::
+
+    $ sudo make install
+    $ kqrcode
+
+Starting a Package
+------------------
+
+``bzr-builddeb`` includes a plugin to create a new package from a template,
+the plugin is a wrapper around the ``dh_make`` command::
+
+    $ sudo apt-get install dh-make
+    $ bzr dh-make kqrcode 0.4 kqrcode-0.4.tar.gz
+
+When it asks what type of package type ``s`` for single binary.
+
+This will import the code into a branch and add the ``debian/`` packaging
+directory.  Have a look at the contents.  Most of the files it adds are only
+needed for specialist packages (such as Emacs modules) so you can start by
+removing the optional example files::
+
+    $ cd kqrcode/debian
+    $ rm *ex *EX
+
+You should now customise each of the files.  
+
+In ``debian/changelog`` change the
+version number to an Ubuntu version: ``0.4-0ubuntu1`` (upstream version 0.4,
+Debian version 0, Ubuntu version 1).  Also change ``unstable`` to the current
+development Ubuntu release such as ``oneiric``.
+
+Much of the package building work is done by a series of scripts
+called ``debhelper``.  The exact behaviour of ``debhelper`` changes
+with new major versions, the compat file instructs ``debhelper`` which
+version to act as.  You will generally want to set this to the most
+recent version which is ``8``.
+
+``control`` contains all the metadata of the package.  The first paragraph
+describes the source package.  The second and and following paragraphs describe
+the binary packages to be built.  We will need to add the packages needed to
+compile the application to ``Build-Depends:`` so set that to::
+
+    Build-Depends: debhelper (>= 7.0.50~), cmake, libqt4-dev, kdelibs5-dev,
+    libqrencode-dev, libzbar-dev, libzbarqt-dev
+
+You will also need to fill in a description of the programme in the
+``Description:`` field.
+
+``copyright`` needs to be filled in to follow the licence of the upstream
+source.  According to the kqrcode/COPYING file this is GNU GPL 3 or later.
+
+``docs`` contains any upstream documentation files you think should be included
+in the final package.
+
+``README.source`` and ``README.Debian`` are only needed if your package has any
+non-standard features, we don't so you can delete them.
+
+``source/format`` can be left as is, this describes the version format of the
+source package and should be ``3.0 (quilt)``.
+
+``rules`` is the most complex file.  This is a Makefile which compiles the
+code and turns it into a binary package.  Fortunately most of the work is
+automatically done these days by ``debhelper 7`` so the universal ``%``
+Makefile target just runs the ``dh`` script which will run everything needed.
+
+Finally commit the code to your packaging branch::
+
+    $ bzr commit
+
+Building the package
+--------------------
+
+Now we need to check that our packaging successfully compiles the package and
+builds the .deb binary package::
+
+    $ bzr builddeb
+
+This should compile the package and place the result in ``../build-area``.  You
+can view the contents of the package with::
+
+    $ lesspipe kqrcode_0.4-0ubuntu1_amd64.deb
+
+Install the package and check it works::
+
+    $ sudo dpkg --install kqrcode_0.4-0ubuntu1_amd64.deb
+
+Next Steps
+----------
+
+Even if it builds the .deb binary package, your packaging may have
+bugs.  Many errors can be automatically detected by our tool
+``lintian`` which can be run on both the source .dsc metadata file and
+the .deb binary package::
+
+    $ lintian kqrcode_0.4-0ubuntu1.dsc
+    $ lintian kqrcode_0.4-0ubuntu1_amd64.deb
+
+A description of each of the problems it reports can be found on the
+`lintian website`_.
+
+After making a fix to the packaging you can rebuild without having to build
+from scratch using::
+
+    $ debuild -nc
+
+FIXME is there a UDD equivalent?
+
+Having checked that the package builds locally you should ensure it builds on a
+clean system using ``pbuilder``::
+
+    $ bzr builddeb -S
+    $ cd ../build-area
+    $ pbuilder-dist oneiric build kqrcode_0.4-0ubuntu1.dsc
+
+When you are happy with your package you will want others to review it.  You
+can upload the branch to Launchpad for review::
+
+    $ bzr push lp:~<lp-username>/+junk/kqrcode-package
+
+You could also upload the source package to REVU for review::
+
+    $ bzr builddeb -S
+    $ cd ..
+    $ dput revu kqrcode_0.4-0ubuntu1.dsc
+
+You will need to log in to REVU before you can upload to it.  The package
+must also be correctly signed by the GPG key you have in Launchpad.  See the
+`REVU wiki page` for full details.
+
+Uploading it to a PPA (Personal Package Archive) will ensure it builds
+and give an easy way for you and others to test the binary packages.
+You will need to set up a PPA in Launchad then upload with ``dput``::
+
+    $ dput ppa:<lp-username> kqrcode_0.4-0ubuntu1.dsc
+
+See :doc:`uploading</udd-uploading>` for more information.
+
+You can ask for reviews in ``#ubuntu-motu`` IRC channel, or on the
+`MOTU mailing list`_.  There might also be a more specific team you
+could ask such as the Kubuntu team for KDE packages.
+
+.. _`posted on KDE-apps.org`: http://kde-apps.org/content/show.php/KQRCode?content=143544
+.. _`version 0.4 from Sourceforge`: http://sourceforge.net/projects/kqrcode/files/kqrcode-0.4.tar.gz/download
+.. _`packages.ubuntu.com`:  http://packages.ubuntu.com/
+.. _`lintian website`: http://lintian.debian.org/tags.html
+.. _`REVU wiki page`: https://wiki.kubuntu.org/MOTU/Packages/REVU
+.. _`MOTU mailing list`: https://lists.ubuntu.com/mailman/listinfo/ubuntu-motu

=== added file 'traditional-packaging.rst'
--- traditional-packaging.rst	1970-01-01 00:00:00 +0000
+++ traditional-packaging.rst	2011-07-20 11:01:36 +0000
@@ -0,0 +1,5 @@
+=====================
+Traditional Packaging
+=====================
+
+FIXME describe traditional packaging here

=== added file 'udd-getting-the-source.rst'
--- udd-getting-the-source.rst	1970-01-01 00:00:00 +0000
+++ udd-getting-the-source.rst	2011-07-20 11:01:36 +0000
@@ -0,0 +1,190 @@
+==================
+Getting the Source
+==================
+
+Source package URLs
+===================
+
+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.  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,
+just prefix the package name with the release's code name.  E.g. to refer to
+Tomboy's source package in Maverick_ use::
+
+    ubuntu:maverick/tomboy
+
+Since they are unique, you can also abbreviate the distro-series name::
+
+    ubuntu:m/tomboy
+
+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:
+
+    debianlp:tomboy
+
+and to access Tomboy in Debian Lenny_ use::
+
+    debianlp:lenny/tomboy
+
+
+.. _`Bazaar`: http://bazaar.canonical.com/en/
+.. _`Intrepid`: https://wiki.ubuntu.com/IntrepidIbex
+.. _Maverick: https://wiki.ubuntu.com/MaverickMeerkat
+.. _Lenny: http://debian.org/releases/stable/
+
+
+Getting the source
+==================
+
+Every source package in Ubuntu has an associated source branch on Launchpad.
+These source branches are updated automatically by Launchpad, although the
+process is not currently foolproof.
+
+There are a couple of things that we do first in order to make the workflow
+more efficient later.  Once you are used to the process you will learn when it
+makes sense to skip these steps.
+
+
+.. _up-to-date:
+
+Ensure the source branch is up-to-date
+--------------------------------------
+
+Once you've determined which source package to work on, you should ensure that
+the source branch for that package on Launchpad is up-to-date.  Some package
+imports fail for various reasons, and the `status of the package importer`_ is
+always available online.  If the source branch for a package you want to work
+on is out of sync, you'll have to use ``apt-get source`` until the import of
+that package is fixed.
+
+Let's say you want to fix a problem in Tomboy in Natty.  First, find out the
+latest binary package versions that are available::
+
+    $ rmadison tomboy | grep natty
+    tomboy | 1.5.2-1ubuntu4 |         natty | source, amd64, i386
+
+You've already seen how to :ref:`determine the source package corresponding to
+this binary package <what-to-fix>`.  For Tomboy, the binary and source
+packages are both named ``tomboy``.
+
+Whenever the package importer processes a new source package version, it adds
+a Bazaar tag corresponding to that new version.  You can use this tag to
+ensure that the import is up-to-date.  To find the tag of the last revision
+committed by the package importer, do::
+
+    $ 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
+the package importer, we can see that the ``tomboy`` source package for Natty
+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.  First find out the
+latest binary package versions that are available::
+
+    $ rmadison initscripts | tail -n 1
+    initscripts | 2.87dsf-4ubuntu25 |       oneiric | amd64, i386
+
+Then determine the source package corresponding to this binary package::
+
+    $ apt-cache showsrc initscripts | grep ^Package:
+    Package: sysvinit
+
+Find the latest tag added by the package importer::
+
+    $ 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
+``2.87dsf-4ubuntu19`` so the source package is out of date, and in fact we can
+verify that by looking at the status package for the package at
+http://package-import.ubuntu.com/status/sysvinit.html.
+
+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
+----------------------------
+
+Okay, you want to work on the Tomboy package in Natty, and you've verified
+that the source package is up-to-date.  Before actually branching the code for
+Tomboy, create a shared repository to hold the branches for this package.
+The shared repository will make future work much more efficient.
+
+Do this using the `bzr init-repo` command, passing it the directory name we
+would like to use::
+
+    $ bzr init-repo tomboy
+
+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 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 `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
+-----------------------------------------
+
+When you want to do something like a `stable release update`_ (SRU), or you
+just want to examine the code in an old release, you'll want to grab the
+branch corresponding to a particular Ubuntu release.  For example, to get the
+Tomboy package for Maverick do::
+
+    $ bzr branch ubuntu:m/tomboy maverick
+
+
+Importing a Debian source package
+---------------------------------
+
+If the package you want to work on is available in Debian but not Ubuntu, it's
+still easy to import the code to a local bzr branch for development.  Let's
+say you want to import the `newpackage` source package.  We'll start by
+creating a shared repository as normal, but we also have to create a working
+tree to which the source package will be imported (remember to cd out of the
+`tomboy` directory created above)::
+
+    $ bzr init-repo newpackage
+    $ 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
+
+As you can see, we just need to provide the remote location of the dsc file,
+and Bazaar will do the rest.  You've now got a Bazaar source branch.
+
+
+.. _`status of the package importer`: http://package-import.ubuntu.com/status
+.. _`file a bug on the UDD project`: https://bugs.launchpad.net/udd
+.. _`stable release update`: https://wiki.ubuntu.com/StableReleaseUpdates

=== modified file 'udd-intro.rst'
--- udd-intro.rst	2011-07-13 11:27:47 +0000
+++ udd-intro.rst	2011-07-20 11:01:36 +0000
@@ -1,202 +1,130 @@
 ===================================================
-Ubuntu Distributed Development - Getting the Source
+Ubuntu Distributed Development - Introduction
 ===================================================
 
-*Ubuntu Distributed Development* (UDD) is a technique for developing Ubuntu
+This guide focuses on packaging using the *Ubuntu Distributed Development* (UDD)
+method.
+
+*Ubuntu Distributed Development* (UDD) is a new technique for developing Ubuntu
 packages that uses tools, processes, and workflows similar to generic
 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.  For an
-introduction to Bazaar see the `Bazaar Five Minute Tutorial
+Traditional Packaging Limitations
+---------------------------------
+
+Traditionally Ubuntu packages have been kept in tar archive files.  A
+traditional source package is made up of the upstream source tar, a "debian" tar
+(or compressed diff file for older packages) containing the packaging and a
+.dsc meta-data file.  To see a traditional package run::
+
+    $ apt-get source kdetoys
+
+This will download the upstream source ``kdetoys_4.6.5.orig.tar.bz2``, the
+packaging ``kdetoys_4.6.5-0ubuntu1.debian.tar.gz`` and the meta-data
+``kdetoys_4.6.5-0ubuntu1~ppa1.dsc``.  Assuming you have dpkg-dev installed it
+will extract these and give you the source package.
+
+Traditional packaging would edit these files and upload.  However this gives
+limited opportunity to collaborate with other developers, changes have to be
+passed around as diff files with no central way to track them and two developers
+can not make changes at the same time.  So most teams have moved to putting
+their packaging in a revision control system.  This makes it easier for several
+developers to work on a package together.  However there is no direct
+connection between the revision control system and the archive packages so the
+two must be manually kept in sync.  Since each team works in its own revision
+control system a prospective developer must first work out where that is and
+how to get the packaging before they can work on the package.
+
+Ubuntu Distributed Development
+------------------------------
+
+With Ubuntu Distributed Development all packages in the Ubuntu (and Debian)
+archive are automatically imported into Bazaar branches on our code hosting
+site Launchpad.  Changes can be made directly to these branches in
+incremental steps and by anyone with commit access.  Changes can also be made
+in forked branched and merged back in with Merge Proposals when they are large
+enough to need review or if they are by someone without direct commit access.
+
+UDD branches are all in a standard location so doing a checkout is easy::
+
+    $ bzr branch ubuntu:kdetoys
+
+The merge history includes two separate branches, one for the upstream source
+and one which adds the ``debian/`` packaging directory::
+
+    $ cd kdetoys
+    $ bzr qlog
+
+(This command uses *qbzr* for a GUI, run ``log`` instead of ``qlog`` for
+console output.)
+
+.. image:: images/kdetoys-udd-branch.png
+
+This UDD branch of *kdetoys* shows the full packaging for each version
+uploaded to Ubuntu with grey circles and the upstream source versions with
+green circles.  Versions are tagged with either the version in Ubuntu such as
+``4:4.2.29-0ubuntu1`` or for the upstream branch with the upstream version
+``upstream-4.2.96``.  
+
+Many Ubuntu packages are based on the packages in Debian, UDD also imports the
+Debian package into our branches.  In the *kdetoys* branch above the Debian
+versions from *unstable* are from the merge with blue circles while those from
+*Debian experimental* are from the merge with yellow circles.  Debian
+released are tagged with their version number e.g. ``4:4.2.2-1``.
+
+So from a UDD branch you can see the complete history of changes to the package
+and compare any two versions.  For example, to see the changes between version
+4.2.2 in Debian and the 4.2.2 in Ubuntu use::
+
+    $ bzr qdiff -r tag:4:4.2.2-1..tag:4:4.2.2-1ubuntu1
+
+(This command uses *qbzr* for a GUI, run ``diff`` instead of ``qdiff`` for
+console output.)
+
+.. image:: images/kdetoys-udd-diff.png
+
+From this we can clearly see what has changed in Ubuntu compared to Debian,
+very handy.
+
+Bazaar
+------
+
+UDD branches use Bazaar, a distributed revision control system intended to be
+easy to use for those familiar with popular systems such as Subversion while
+offering the power of Git.
+
+To do packaging with UDD you will need to know the basics of how to use
+Bazaar to manage files.  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 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.  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,
-just prefix the package name with the release's code name.  E.g. to refer to
-Tomboy's source package in Maverick_ use::
-
-    ubuntu:maverick/tomboy
-
-Since they are unique, you can also abbreviate the distro-series name::
-
-    ubuntu:m/tomboy
-
-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:
-
-    debianlp:tomboy
-
-and to access Tomboy in Debian Lenny_ use::
-
-    debianlp:lenny/tomboy
-
-
-.. _`Bazaar`: http://bazaar.canonical.com/en/
-.. _`Intrepid`: https://wiki.ubuntu.com/IntrepidIbex
-.. _Maverick: https://wiki.ubuntu.com/MaverickMeerkat
-.. _Lenny: http://debian.org/releases/stable/
-
-
-Getting the source
-==================
-
-Every source package in Ubuntu has an associated source branch on Launchpad.
-These source branches are updated automatically by Launchpad, although the
-process is not currently foolproof.
-
-There are a couple of things that we do first in order to make the workflow
-more efficient later.  Once you are used to the process you will learn when it
-makes sense to skip these steps.
-
-
-.. _up-to-date:
-
-Ensure the source branch is up-to-date
---------------------------------------
-
-Once you've determined which source package to work on, you should ensure that
-the source branch for that package on Launchpad is up-to-date.  Some package
-imports fail for various reasons, and the `status of the package importer`_ is
-always available online.  If the source branch for a package you want to work
-on is out of sync, you'll have to use ``apt-get source`` until the import of
-that package is fixed.
-
-Let's say you want to fix a problem in Tomboy in Natty.  First, find out the
-latest binary package versions that are available::
-
-    $ rmadison tomboy | grep natty
-    tomboy | 1.5.2-1ubuntu4 |         natty | source, amd64, i386
-
-You've already seen how to :ref:`determine the source package corresponding to
-this binary package <what-to-fix>`.  For Tomboy, the binary and source
-packages are both named ``tomboy``.
-
-Whenever the package importer processes a new source package version, it adds
-a Bazaar tag corresponding to that new version.  You can use this tag to
-ensure that the import is up-to-date.  To find the tag of the last revision
-committed by the package importer, do::
-
-    $ 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
-the package importer, we can see that the ``tomboy`` source package for Natty
-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.  First find out the
-latest binary package versions that are available::
-
-    $ rmadison initscripts | tail -n 1
-    initscripts | 2.87dsf-4ubuntu25 |       oneiric | amd64, i386
-
-Then determine the source package corresponding to this binary package::
-
-    $ apt-cache showsrc initscripts | grep ^Package:
-    Package: sysvinit
-
-Find the latest tag added by the package importer::
-
-    $ 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
-``2.87dsf-4ubuntu19`` so the source package is out of date, and in fact we can
-verify that by looking at the status package for the package at
-http://package-import.ubuntu.com/status/sysvinit.html.
-
-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
-----------------------------
-
-Okay, you want to work on the Tomboy package in Natty, and you've verified
-that the source package is up-to-date.  Before actually branching the code for
-Tomboy, create a shared repository to hold the branches for this package.
-The shared repository will make future work much more efficient.
-
-Do this using the `bzr init-repo` command, passing it the directory name we
-would like to use::
-
-    $ bzr init-repo tomboy
-
-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 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 `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
------------------------------------------
-
-When you want to do something like a `stable release update`_ (SRU), or you
-just want to examine the code in an old release, you'll want to grab the
-branch corresponding to a particular Ubuntu release.  For example, to get the
-Tomboy package for Maverick do::
-
-    $ bzr branch ubuntu:m/tomboy maverick
-
-
-Importing a Debian source package
----------------------------------
-
-If the package you want to work on is available in Debian but not Ubuntu, it's
-still easy to import the code to a local bzr branch for development.  Let's
-say you want to import the `newpackage` source package.  We'll start by
-creating a shared repository as normal, but we also have to create a working
-tree to which the source package will be imported (remember to cd out of the
-`tomboy` directory created above)::
-
-    $ bzr init-repo newpackage
-    $ 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
-
-As you can see, we just need to provide the remote location of the dsc file,
-and Bazaar will do the rest.  You've now got a Bazaar source branch.
-
+Limitations of UDD
+------------------
+
+Ubuntu Distributed Development is a new method for working with Ubuntu
+packages.  It currently has some notable limitations:
+
+* Doing a full branch with history can take a lot of time and network
+  resources.  You may find it quicker to do a lightweight checkout ``bzr
+  checkout --lightweight ubuntu:kdetoys`` but this will need a network access
+  for any further bzr operations.
+
+* Working with patches is fiddly.  Patches can be seen as a branched revision
+  control system, so we end up with RCS on top of RCS.
+
+* There is no way to build directly from branches.  You need to create a source
+  package and upload that.
+
+* Some packages have not been successfully imported into UDD branches.  You
+  should check the `status of the package importer`_ before working on a branch.
+
+All of the above are being worked on and UDD is expected to become the main way
+to work on Ubuntu packages soon.  However currently most teams within Ubuntu do
+not yet work with UDD branches for their  development.  However because UDD
+branches are the same as the packages in the  archive any team should be able to
+accept merges against them.
 
 .. _`status of the package importer`: http://package-import.ubuntu.com/status
-.. _`file a bug on the UDD project`: https://bugs.launchpad.net/udd
-.. _`stable release update`: https://wiki.ubuntu.com/StableReleaseUpdates