ubuntu-packaging-guide-team team mailing list archive

[Jonathan Riddell <jriddell@xxxxxxxxxx>]

Jonathan Riddell has proposed merging lp:~jr/ubuntu-packaging-guide/03-packaging-from-scratch into lp:ubuntu-packaging-guide with lp:~jr/ubuntu-packaging-guide/02-udd-introduction as a prerequisite.

Requested reviews:
  Barry Warsaw (barry)
Related bugs:
  Bug #702006 in Ubuntu Packaging Guide: "Add article "Packaging from Scratch""
  https://bugs.launchpad.net/ubuntu-packaging-guide/+bug/702006

For more details, see:
https://code.launchpad.net/~jr/ubuntu-packaging-guide/03-packaging-from-scratch/+merge/68817

Add a packaging from scratch guide

-- 
https://code.launchpad.net/~jr/ubuntu-packaging-guide/03-packaging-from-scratch/+merge/68817
Your team Ubuntu Packaging Guide Team is subscribed to branch lp:ubuntu-packaging-guide.

=== 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-22 10:40:26 +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-22 10:40:26 +0000 differ
=== modified file 'index.rst'
--- index.rst	2011-07-19 13:13:58 +0000
+++ index.rst	2011-07-22 10:40:26 +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-22 10:40:26 +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-22 10:40:26 +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-22 10:40:26 +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-22 10:40:26 +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