ubuntu-packaging-guide-team team mailing list archive

[Barry Warsaw <barry@xxxxxxxxxxxxx>]

Barry Warsaw has proposed merging lp:~barry/ubuntu-packaging-guide/udd 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/+merge/48685

First cut at integrating UDD docs from the wiki page.  Also, much cleaning and consistency of style, typos, etc.
-- 
https://code.launchpad.net/~barry/ubuntu-packaging-guide/udd/+merge/48685
Your team Ubuntu Packaging Guide Team is requested to review the proposed merge of lp:~barry/ubuntu-packaging-guide/udd into lp:ubuntu-packaging-guide.

=== modified file 'fixing-a-bug.rst'
--- fixing-a-bug.rst	2011-01-11 21:23:06 +0000
+++ fixing-a-bug.rst	2011-02-05 01:46:53 +0000
@@ -1,8 +1,9 @@
+======================
 Fixing a bug in Ubuntu
 ======================
 
 Introduction
-------------
+============
 
 If you followed the instructions to :doc:`get set up with Ubuntu 
 Development</getting-set-up>`, you should be all set and ready to go.
@@ -16,7 +17,7 @@
 
 
 Finding the problem
--------------------
+===================
 
 There is a lot of different ways to find things to work on. It might be a bug
 report you are encountering yourself (which gives you a good opportunity to
@@ -28,25 +29,69 @@
 it out and find your first bug to work on.
 
 
-Get the code
-------------
-
-If you know which source package contains the code that shows the problem, it 
-is trivial. Just type in::
-
-  bzr branch lp:ubuntu/<packagename>
-
-where ``<packagename>`` is the name of the source package. This will check out
-the code of the latest Ubuntu development release. If you need the code of a 
-stable release, let's say ``hardy``, you would type in::
-
-  bzr branch lp:ubuntu/hardy/<packagename>
+.. _what-to-fix:
+
+Figuring out what to fix
+========================
+
+If you don't know the source package containing the code that has the problem,
+but you do know the path to the affected program on your system, you can
+discover the source package that you'll need to work on.
+
+Let's say you've found a bug in Tomboy, a note taking desktop application.
+The Tomboy application can be started by running ``/usr/bin/tomboy`` on the
+command line.  To find the binary package containing this application, use
+this command::
+
+    $ apt-file find /usr/bin/tomboy
+
+This would print out::
+
+    tomboy: /usr/bin/tomboy
+
+Note that the part preceding the colon is the binary package name.  It's often
+the case that the source package and binary package will have different names.
+This is most common when a single source package is used to build multiple
+different binary packages.  To find the source package for a particular binary
+package, type::
+
+    $ apt-cache show tomboy | grep ^Source:
+
+In this case, nothing is printed, meaning that ``tomboy`` is also the name of
+the binary package.  An example where the source and binary package names
+differ is ``python-vigra``.  While that is the binary package name, the source
+package is actually ``libvigraimpex`` and can be found with this command (and
+its output)::
+
+    $ apt-cache show python-vigra | grep ^Source:
+    Source: libvigraimpex
 
 .. XXX: Link to SRU article.
 
 
-Work on fix
------------
+Getting the code
+================
+
+Once you know the source package to work on, you will want to get a copy of
+the code on your system, so that you can debug it.  This is done by
+*branching* the source package branch corresponding to the source package.
+Launchpad maintains source package branches for all the packages in Ubuntu.
+
+Once you've got a local branch of the source package, you can investigate the
+bug, create a fix, and upload your proposed fix to Launchpad, in the form of a
+Bazaar branch.  When you are happy with your fix, you can submit a *merge
+proposal*, which asks other Ubuntu developers to review and approve your
+change.  If they agree with your changes, an Ubuntu developer will upload the
+new version of the package to Ubuntu so that everyone gets the benefit or your
+excellent fix - and you get a little bit of credit.  You're now on your way to
+becoming an Ubuntu developer!
+
+We'll describe specifics on how to branch the code, push your fix, and request
+a review in the following sections.
+
+
+Work on a fix
+=============
 
 There are entire books written about finding bugs, fixing them, testing them, 
 etc. If you are completely new to programming, try to fix easy bugs such as
@@ -62,110 +107,10 @@
 
 .. XXX: Link to 'update to a new version' article.
 
-
-If you find a patch to fix the problem, running this command in the source 
-directory should apply the patch::
-
-  patch -p1 < ../bugfix.patch
+If you find a patch to fix the problem, say, attached to a bug report, running
+this command in the source directory should apply the patch::
+
+    $ patch -p1 < ../bugfix.patch
 
 Refer to the ``patch(1)`` manpage for options and arguments such as 
 ``--dry-run``, ``-p<num>``, etc.
-
-
-Testing the fix
----------------
-
-To build a test package with your changes, run these commands::
-
-  bzr bd -- -S -us -uc
-  pbuilder-dist <release> build ../<package>_<version>.dsc
-
-This will create a source package from the branch contents (``-us -uc`` will 
-just omit the step to sign the source package) and pbuilder-dist will build
-the package from source for whatever ``release`` you choose.
-
-Once the build succeeded, install the package from 
-``~/pbuilder/<release>_result/`` (using ``sudo dpkg -i 
-<package>_<version>.deb``). Then test to see if the bug is fixed.
-
-
-
-Documenting the fix
--------------------
-
-It is very important to document your change sufficiently so developers who 
-look at the code in the future won't have to guess what your reasoning was and
-what your assumptions were. Every Debian and Ubuntu package source includes 
-``debian/changelog``, where changes of each uploaded package are tracked.
-
-The easiest way to do this is to run::
-
-  dch -i
-
-This will add a boilerplate changelog entry for you and launch an editor 
-where you can fill out the blanks. An example of this could be::
-
-  specialpackage (1.2-3ubuntu4) natty; urgency=low
-
-    * debian/control: updated description to include frobnicator (LP: #123456)
-
-   -- Emma Adams <emma.adams@xxxxxxx>  Sat, 17 Jul 2010 02:53:39 +0200
-
-``dch`` should fill out the first and last line of such a changelog entry for
-you already. Line 1 consists of the source package name, the version number,
-which Ubuntu release it is uploaded to, the urgency (which almost always is 
-'low'). The last line always contains the name, email address and timestamp
-(in RFC 2822 format) of the change.
-
-With that out of the way, let's focus on the actual changelog entry itself: 
-it is very important to document:
-
-  #. where the change was done
-  #. what was changed
-  #. where the discussion of the change happened
-
-In our (very sparse) example the last point is covered by "(LP: #123456)" 
-which refers to Launchpad bug 123456. Bug reports or mailing list threads
-or specifications are usually good information to provide as a rationale for a
-change. As a bonus, if you use the ``LP: #<number>`` notation for Launchpad
-bugs, the bug will be automatically closed when the package is uploaded to 
-Ubuntu.
-
-
-Committing the fix
-------------------
-
-With the changelog entry written and saved, you can just run::
-
-  debcommit
-
-and the change will be committed (locally) with your changelog entry as a 
-commit message.
-
-To push it to Launchpad, as the remote branch name, you need to stick to the 
-following nomenclature::
-
-  lp:~<yourlpid>/ubuntu/<release>/<package>/<branchname>
-
-This could for example be::
-
-  lp:~emmaadams/ubuntu/natty/specialpackage/fix-for-123456
-
-So if you just run::
-
-  bzr push lp:~emmaadams/ubuntu/natty/specialpackage/fix-for-123456
-  bzr lp-open
-
-you should be all set. The push command should push it to Launchpad and the 
-second command will open the Launchpad page of the remote branch in your 
-browser. There find the "(+) Propose for merging" link, click it to get the
-change reviewed by somebody and included in Ubuntu.
-
-
-Conclusion
-----------
-
-.. XXX: link to 'forwarding patches' article
-.. XXX: link to 'debdiff' article (in case of slow internet, package not 
-        imported, etc.)
-

=== modified file 'getting-set-up.rst'
--- getting-set-up.rst	2010-12-08 11:46:02 +0000
+++ getting-set-up.rst	2011-02-05 01:46:53 +0000
@@ -1,118 +1,123 @@
+==============
 Getting Set Up
 ==============
 
 There are a number of things you need to do in the beginning to enable you to
 do Ubuntu development. A few of them you have to do locally on your system.
-In addition to that you also need to inform Launchpad about yourself, so it
+In addition to that you also need to inform Launchpad_ about yourself, so it
 accepts changes you want to make.
 
-When you followed all the steps in this article, 
+When you followed all the steps in this article,
 
 * you have all the tools to do Ubuntu development installed on your machine,
 * your local developer tools know about you, which simplifies work a lot,
 * you can do local builds of packages,
 * you can interact with other developers and propose your changes on Launchpad
   to get merged,
-* you can upload packages to Launchpad, so they are hosted in your Personal 
+* you can upload packages to Launchpad, so they are hosted in your Personal
   Package Archive (PPA).
 
 
-Running the development version
--------------------------------
-
-It is advisable to run the current development version of Ubuntu. It will 
-allow you to test changes in a "live environment" where they are actually 
-built and tested in the development release you uploade them to.
-
-https://wiki.ubuntu.com/UsingDevelopmentReleases shows a variety of ways to 
+Run the development version
+===========================
+
+It is advisable to run the current development version of Ubuntu. It will
+allow you to test changes in a "live environment" where they are actually
+built and tested in the development release you upload them to.
+
+https://wiki.ubuntu.com/UsingDevelopmentReleases shows a variety of ways to
 use the development release in a safe way.
 
 
-
-Installing tools locally
-------------------------
-
-Just run::
-
-  sudo apt-get install gnupg pbuilder ubuntu-dev-tools bzr-builddeb
-
-and you should have all the tools you will need in the beginning.
-
-* ``gnupg`` you will need to create a GPG key with which you will sign files
-  you want to upload to Launchpad.
-* ``pbuilder`` is a great tool to do a reproducible build of a package in a 
+Install the tools locally
+=========================
+
+There are a number of tools that will make your life as an Ubuntu developer
+much easier.  You'll encounter these tools later in this guide.  To install
+most of the tools you'll need, run this command::
+
+    $ sudo apt-get install gnupg pbuilder ubuntu-dev-tools bzr-builddeb apt-file apt-cache
+
+These packages include:
+
+* ``gnupg`` -- `GNU Privacy Guard`_ contains tools you will need to create a
+  cryptographic key with which you will sign files you want to upload to
+  Launchpad.
+* ``pbuilder`` -- a tool to do a reproducible builds of a package in a
   clean and isolated environment.
-* ``ubuntu-dev-tools`` (and ``devscripts``, a direct dependency) provide you
-  with a collection of tools that make a lot of packaging tasks a lot easier.
-* ``bzr-builddeb`` (and ``bzr``, a dependency) will get you set up for working
-  in the distributed development environment, that makes it easy for many 
-  developers to collaborate and work on the same code while keeping it trivial
-  to merge each others work.
+* ``ubuntu-dev-tools`` (and ``devscripts``, a direct dependency) -- a
+  collection of tools that make many packaging tasks easier.
+* ``bzr-builddeb`` (and ``bzr``, a dependency) -- distributed version control
+  tools that makes it easy for many developers to collaborate and work on the
+  same code while keeping it trivial to merge each others work.
+* ``apt-file`` provides an easy way to find the binary package that contains a
+  given file.
+* ``apt-cache`` provides even more information about packages on Ubuntu.
 
 
 Setting up a GPG key
---------------------
+====================
 
-GPG stands for `GNU Privacy Guard` and implements the OpenPGP standard which
-allows you to sign and encrypt messages and files. This is useful for a number
-of purposes. In our case it is important that you can sign files with your 
-key, so they can be identified as something that you worked on. If you upload
-a source package to Launchpad, it will only accept the package if it can tell
-who uploaded the package.
+GPG stands for `GNU Privacy Guard`_ and it implements the OpenPGP standard
+which allows you to sign and encrypt messages and files. This is useful for a
+number of purposes. In our case it is important that you can sign files with
+your key, so they can be identified as something that you worked on. If you
+upload a source package to Launchpad, it will only accept the package if it
+can absolutely determine who uploaded the package.
 
 To generate a new GPG key, run::
 
-  gpg --key-gen
+    $ gpg --key-gen
 
-GnuPG will first ask you which kind of key you want to generate. Choosing the 
-default (RSA and DSA) is fine. Next it will ask you about the keysize. The 
-default (currently 2048) is fine, but 4096 is more secure. Afterwards it will
+GPG will first ask you which kind of key you want to generate. Choosing the
+default (RSA and DSA) is fine. Next it will ask you about the keysize. The
+default (currently 2048) is fine, but 4096 is more secure. Afterward, it will
 ask you if you want it to expire the key at some stage. It is safe to say "0",
 which means the key will never expire. The last questions will be about your
 name and email address. Just pick the ones you are going to use for Ubuntu
-development here, you can add additional email addresses later on. Adding a 
-comment is not necessary. Then you will have to set a passphrase. Choose a 
-safe one. Now GnuPG will create a key for you, which can take a little bit 
-of time, as it needs random bytes, so if you give the system some work to
-do it will be just fine.
+development here, you can add additional email addresses later on. Adding a
+comment is not necessary. Then you will have to set a passphrase. Choose a
+safe one. Now GPG will create a key for you, which can take a little bit of
+time; it needs random bytes, so if you give the system some work to do it will
+be just fine.  Move the cursor around!
 
 Once this is done, you will get a message similar to this one::
 
-  pub   4096R/43CDE61D 2010-12-06
-        Key fingerprint = 5C28 0144 FB08 91C0 2CF3  37AC 6F0B F90F 43CD E61D
-  uid                  Daniel Holbach <dh@xxxxxxxxxxxxxx>
-  sub   4096R/51FBE68C 2010-12-06
-
-In this case ``43CDE61D`` is they key ID. 
-
-To upload (the public part of) of your key to a keyserver, so the world can 
+    pub   4096R/43CDE61D 2010-12-06
+          Key fingerprint = 5C28 0144 FB08 91C0 2CF3  37AC 6F0B F90F 43CD E61D
+    uid                  Daniel Holbach <dh@xxxxxxxxxxxxxx>
+    sub   4096R/51FBE68C 2010-12-06
+
+In this case ``43CDE61D`` is the *key ID*.
+
+To upload (the public part of) of your key to a keyserver, so the world can
 identify messages and files as yours, just run::
 
-  gpg --send-keys <KEY ID>
+    $ gpg --send-keys <KEY ID>
 
 There is a network of keyservers that will automatically sync the key between
-them.
+themselves.
+
 
 Setting up an SSH key
----------------------
+=====================
 
-SSH is a network protocol that allows you to exchange data in a secure way 
-over the network. In a lot of cases you will use it to access and open a 
-shell on another machine. It is also very useful to transfer files in a secure
-way.
+SSH_ is a network protocol that allows you to exchange data in a secure way
+over the network. In a lot of cases you will use it to access and open a shell
+on another machine. It is also very useful to transfer files in a secure way.
 
 To generate a SSH key, run::
 
-  ssh-keygen -t rsa
+    $ ssh-keygen -t rsa
 
-The default filename makes sense, you can just leave it as it is. Also you 
-can choose to use a passphrase or not.
+The default file name usually makes sense, so you can just leave it as it is.
+For security purposes, it's highly recommended that you use a passphrase.
 
 We will use the SSH key to securely push code changes to Launchpad.
 
 
 Setting up pbuilder
--------------------
+===================
 
 ``pbuilder`` allows you to build packages locally on your machine. It serves
 a couple of purposes:
@@ -120,139 +125,156 @@
 * the build will be done in a minimal and clean environment, where you can
   see if it succeeds in a reproducible way (with no modifications of the local
   system
-* there is no need to install all necessary `build-dependencs` locally
+* there is no need to install all necessary *build dependencies* locally
 * you can set up multiple instances for various Ubuntu and Debian releases
 
-Setting ``pbuilder`` up is very easy. Edit `~/.pbuilderrc` and add the 
+Setting ``pbuilder`` up is very easy. Edit `~/.pbuilderrc` and add the
 following line to it::
 
-  COMPONENTS="main universe multiverse restricted"
+    COMPONENTS="main universe multiverse restricted"
 
-This will ensure that `build-dependends` are satisfied using all components.
+This will ensure that build dependencies are satisfied using all components.
 
 Then run::
 
-  pbuilder-dist <release> create
+    $ pbuilder-dist <release> create
 
 where <release> is for example `natty`, `maverick`, `lucid` or in the case of
-Debian maybe `sid`. This will take a while as it will download all the 
+Debian maybe `sid`. This will take a while as it will download all the
 necessary packages for a "minimal installation". These will be cached though.
 
 
-Setting up your development environment
----------------------------------------
-
-Teaching Bazaar about you
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Bazaar is the tool we use to store code changes in a logical way, to exchange
-proposed changes and merge them, even if development is done concurrently.
-
-To tell Bazaar who you are, simply run::
-
-  bzr whoami "Frank Chu <fchu@xxxxxxxxxxx>"
-  bzr launchpad-login fchu
-
-`whoami` will tell Bazaar which name and email address it should use for your 
-commit messages. With `launchpad-login` you set your Launchpad ID. This way 
-code that you publish in Launchpad will be associated with you.
-
-Note: If you can not remember the ID, go to https://launchpad.net/people/+me 
-and see where it redirects you. The part after the "~" in the URL is your 
-Launchpad ID.)
-
-
-Introducing you to the development tools
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Similar to Bazaar, the Debian/Ubuntu packaging tools need to learn about you
-as well. Simply open your `~/.bashrc` in a text editor and add something like 
-this to the bottom of it::
-
-  export DEBFULNAME="Frank Chu"
-  export DEBEMAIL="fchu@xxxxxxxxxxx"
-
-
-Now save the file and either restart your terminal or run::
-
-  source ~/.bashrc
-
-(If you use a different than the default shell, which is `bash`, please edit
-the configuration file for that shell accordingly.)
+Set up your development environment
+===================================
+
+There are a few things you'll need to set up in your development environment
+before you can start working on packages.
 
 
 Launchpad
 ---------
+
 Launchpad is the central piece of infrastructure we use in Ubuntu. It stores
 not only our packages and our code, but also things like translations, bug
-reports, information about the people who work on Ubuntu and which teams they 
-are part of.
-
-You will need to register with Launchpad and give it some information about 
-you so you can get started and it will accept packages, bug reports, code
-branches, etc. from you.
-
-
-Setting up a profile
-^^^^^^^^^^^^^^^^^^^^
-
-Generally it should be enough to head to https://launchpad.net/+login and 
-enter your email address. It will send back an email to you with a link you
-need to open in your browser. (If you don not receive it, check in your Spam
-folder too.)
-
-Next you will have to choose a display name. Almost everybody just uses their
-real name here.
-
-https://help.launchpad.net/YourAccount/NewAccount has more information about 
+reports, information about the people who work on Ubuntu and which teams they
+are part of.  You'll also use Launchpad to publish your proposed fixes, and
+get other Ubuntu developers to review and sponsor them.
+
+You will need to register with Launchpad and provide a minimal amount of
+information, so that you can download and upload code, submit bug reports, and
+more.
+
+
+Setting up an account
+---------------------
+
+If you don't already have a Launchpad account, you can easily `create one`_.
+If you have a Launchpad account but cannot remember your Launchpad id, you can
+find this out by going to https://launchpad.net/people/+me and looking for the
+part after the `~` in the URL.
+
+Launchpad's registration process will ask you to choose a display name. It's
+encouraged for you to use your real name here. so that your Ubuntu developer
+colleagues will be able to get to know you better.
+
+When you register a new account, Launchpad will send you an email with a link
+you need to open in your browser, in order to verify your email address. If
+you don't receive it, check in your spam folder.
+
+https://help.launchpad.net/YourAccount/NewAccount has more information about
 the process and additional settings you can change.
 
 
 Uploading the GPG key to Launchpad
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------
 
 To find about your GPG fingerprint, run::
 
-  gpg --fingerprint <email@xxxxxxxxxxx>
+    $ gpg --fingerprint <email@xxxxxxxxxxx>
 
 and it will print out something like::
 
-  pub   4096R/43CDE61D 2010-12-06
-        Key fingerprint = 5C28 0144 FB08 91C0 2CF3  37AC 6F0B F90F 43CD E61D
-  uid                  Daniel Holbach <dh@xxxxxxxxxxxxxx>
-  sub   4096R/51FBE68C 2010-12-06
+    pub   4096R/43CDE61D 2010-12-06
+          Key fingerprint = 5C28 0144 FB08 91C0 2CF3  37AC 6F0B F90F 43CD E61D
+    uid                  Daniel Holbach <dh@xxxxxxxxxxxxxx>
+    sub   4096R/51FBE68C 2010-12-06
 
 
 Head to https://launchpad.net/people/+me/+editpgpkeys and copy the part about
-your "Key fingerprint" into the text box. In the case above this would be 
-``5C28 0144 FB08 91C0 2CF3  37AC 6F0B F90F 43CD E61D``. Now click on "Import 
+your "Key fingerprint" into the text box. In the case above this would be
+``5C28 0144 FB08 91C0 2CF3  37AC 6F0B F90F 43CD E61D``. Now click on "Import
 Key".
 
-Launchpad will use the fingerprint to check the Ubuntu key server for your 
-key and, if successful, send you an encrypted email asking you to confirm 
-the key import. Check your email account and read the email that Launchpad 
-sent you. `If your email client supports OpenPGP encryption, it will prompt 
-you for the password you chose for the key when GPG generated it. Enter the 
+Launchpad will use the fingerprint to check the Ubuntu key server for your
+key and, if successful, send you an encrypted email asking you to confirm
+the key import. Check your email account and read the email that Launchpad
+sent you. `If your email client supports OpenPGP encryption, it will prompt
+you for the password you chose for the key when GPG generated it. Enter the
 password, then click the link to confirm that the key is yours.`
 
-Launchpad encrypts the email, using your public key, so that it can be sure 
-that the key is yours. If your email software does not support OpenPGP 
-encryption, copy the encrypted email's contents, type ``gpg`` in your 
-terminal, then paste the email contents into your terminal window. 
-
-Back on the Launchpad website, use the Confirm button and Launchpad will 
-complete the import of your OpenPGP key. 
-
-Find more information at 
+Launchpad encrypts the email, using your public key, so that it can be sure
+that the key is yours. If your email software does not support OpenPGP
+encryption, copy the encrypted email's contents, type ``gpg`` in your
+terminal, then paste the email contents into your terminal window.
+
+Back on the Launchpad website, use the Confirm button and Launchpad will
+complete the import of your OpenPGP key.
+
+Find more information at
 https://help.launchpad.net/YourAccount/ImportingYourPGPKey
 
 Uploading your SSH key
-^^^^^^^^^^^^^^^^^^^^^^
+----------------------
 
 Open https://launchpad.net/people/+me/+editsshkeys in a web browser, also open
-``~/.ssh/id_rsa.pub`` in a text editor. It is the public part of your SSH key, 
-so it is safe to share it with Launchpad. Copy the contents of the file and 
-paste them into the text box on the web page that says "Add an SSH key". Now 
+``~/.ssh/id_rsa.pub`` in a text editor. It is the public part of your SSH key,
+so it is safe to share it with Launchpad. Copy the contents of the file and
+paste them into the text box on the web page that says "Add an SSH key". Now
 click "Import Public Key".
 
-More information is available at 
+More information is available at
 https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair
+
+
+Teaching Bazaar about you
+-------------------------
+
+Bazaar is the tool we use to store code changes in a logical way, to exchange
+proposed changes and merge them, even if development is done concurrently.
+
+To tell Bazaar who you are, simply run::
+
+    $ bzr whoami "Bob Dobbs <subgenius@xxxxxxxxxxx>"
+    $ bzr launchpad-login subgenius
+
+`whoami` will tell Bazaar which name and email address it should use for your
+commit messages. With `launchpad-login` you set your Launchpad ID. This way
+code that you publish in Launchpad will be associated with you.
+
+Note: If you can not remember the ID, go to https://launchpad.net/people/+me
+and see where it redirects you. The part after the "~" in the URL is your
+Launchpad ID.)
+
+
+Introducing you to the development tools
+----------------------------------------
+Similar to Bazaar, the Debian/Ubuntu packaging tools need to learn about you
+as well. Simply open your `~/.bashrc` in a text editor and add something like
+this to the bottom of it::
+
+    $ export DEBFULNAME="Bob Dobbs"
+    $ export DEBEMAIL="subgenius@xxxxxxxxxxx"
+
+
+Now save the file and either restart your terminal or run::
+
+    $ source ~/.bashrc
+
+(If you use a different than the default shell, which is `bash`, please edit
+the configuration file for that shell accordingly.)
+
+
+.. _`GNU Privacy Guard`: http://gnupg.org/
+.. _SSH: http://www.openssh.com/
+.. _Launchpad: http://launchpad.net
+.. _`create one`: https://launchpad.net/+login

=== modified file 'index.rst'
--- index.rst	2010-12-06 16:36:30 +0000
+++ index.rst	2011-02-05 01:46:53 +0000
@@ -14,6 +14,16 @@
    introduction-to-ubuntu-development
    getting-set-up
    fixing-a-bug
+   udd-intro
+   udd-working
+   udd-sponsorship
+   udd-uploading
+   udd-latest
+   udd-merging
+   udd-patchsys
+   udd-newpackage
+   testing
+
 
 Indices and tables
 ==================
@@ -21,4 +31,3 @@
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

=== modified file 'introduction-to-ubuntu-development.rst'
--- introduction-to-ubuntu-development.rst	2010-12-13 15:23:22 +0000
+++ introduction-to-ubuntu-development.rst	2011-02-05 01:46:53 +0000
@@ -1,3 +1,4 @@
+==================================
 Introduction to Ubuntu Development
 ==================================
 

=== added file 'testing.rst'
--- testing.rst	1970-01-01 00:00:00 +0000
+++ testing.rst	2011-02-05 01:46:53 +0000
@@ -0,0 +1,67 @@
+===============
+Testing the fix
+===============
+
+To build a test package with your changes, run these commands::
+
+    $ bzr bd -S -- -us -uc
+    $ pbuilder-dist <release> build ../<package>_<version>.dsc
+
+This will create a source package from the branch contents (``-us -uc`` will
+just omit the step to sign the source package) and ``pbuilder-dist`` will
+build the package from source for whatever ``release`` you choose.
+
+Once the build succeeded, install the package from 
+``~/pbuilder/<release>_result/`` (using ``sudo dpkg -i 
+<package>_<version>.deb``).  Then test to see if the bug is fixed.
+
+
+Documenting the fix
+===================
+
+It is very important to document your change sufficiently so developers who 
+look at the code in the future won't have to guess what your reasoning was and
+what your assumptions were. Every Debian and Ubuntu package source includes 
+``debian/changelog``, where changes of each uploaded package are tracked.
+
+The easiest way to do this is to run::
+
+    $ dch -i
+
+This will add a boilerplate changelog entry for you and launch an editor 
+where you can fill out the blanks. An example of this could be::
+
+  specialpackage (1.2-3ubuntu4) natty; urgency=low
+
+    * debian/control: updated description to include frobnicator (LP: #123456)
+
+   -- Emma Adams <emma.adams@xxxxxxx>  Sat, 17 Jul 2010 02:53:39 +0200
+
+``dch`` should fill out the first and last line of such a changelog entry for
+you already. Line 1 consists of the source package name, the version number,
+which Ubuntu release it is uploaded to, the urgency (which almost always is 
+'low'). The last line always contains the name, email address and timestamp
+(in :rfc:5322 format) of the change.
+
+With that out of the way, let's focus on the actual changelog entry itself: 
+it is very important to document:
+
+    #. where the change was done
+    #. what was changed
+    #. where the discussion of the change happened
+
+In our (very sparse) example the last point is covered by ``(LP: #123456)``
+which refers to Launchpad bug 123456. Bug reports or mailing list threads or
+specifications are usually good information to provide as a rationale for a
+change. As a bonus, if you use the ``LP: #<number>`` notation for Launchpad
+bugs, the bug will be automatically closed when the package is uploaded to
+Ubuntu.
+
+
+Conclusion
+==========
+
+.. XXX: link to 'forwarding patches' article
+.. XXX: link to 'debdiff' article (in case of slow internet, package not 
+        imported, etc.)
+

=== added file 'udd-intro.rst'
--- udd-intro.rst	1970-01-01 00:00:00 +0000
+++ udd-intro.rst	2011-02-05 01:46:53 +0000
@@ -0,0 +1,224 @@
+==============================
+Ubuntu Distributed Development
+==============================
+
+*Ubuntu Distributed Development* (UDD) is a technique for developing Ubuntu
+packages that uses tools, processes, and workflows similar to generic
+distributed version control (dVCS) system-based software development.  The
+dVCS used for UDD is Bazaar_.
+
+You should already be familiar with basic Bazaar usage and workflow.  Ubuntu
+Intrepid_ or later is required for these instructions to work.
+
+
+Source package URLs
+===================
+
+Bazaar provides some very nice shortcuts for accessing the source branches of
+packages in both Ubuntu and Debian (on Launchpad).  These shortcuts are
+available in Bazaar version 2.3 or newer.  You can still access source
+branches in older versions of Bazaar, using a slightly more verbose syntax.
+
+The examples in this guide always use the ``ubuntu:`` prefix.
+
+
+Source branch shortcuts
+-----------------------
+
+To refer to source branches use::
+
+    ubuntu:package
+
+where *package* refers to the package name you're interested in.  This URL
+refers to the package in the current development version of Ubuntu.  As of
+this writing (2011-02-04) that version is Natty_ which will be released as
+Ubuntu 11.04.  Thus, to refer to the branch of Tomboy in Natty, you would
+use::
+
+    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
+
+
+Explicit source branches
+------------------------
+
+If you're using an older version of Bazaar, the ``ubuntu:`` and ``debianlp:``
+prefixes won't be available to you.  Instead use the ``lp:`` prefix to access
+the source branch.  For example, Tomboy in the latest Ubuntu development
+release is available at::
+
+    lp:ubuntu/tomboy
+
+while the Maverick version is available at::
+
+    lp:ubuntu/maverick/tomboy
+
+and the Debian Lenny version is available at::
+
+    lp:debian/lenny/tomboy
+
+
+.. _`Bazaar`: http://bazaar.canonical.com/en/
+.. _`Intrepid`: https://wiki.ubuntu.com/IntrepidIbex
+.. _Natty: https://wiki.ubuntu.com/NattyNarwhal
+.. _Maverick: https://wiki.ubuntu.com/MaverickMeerkat
+.. _Lenny: http://debian.org/releases/stable/
+
+
+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 -l 1 ubuntu:tomboy | grep ^tags:
+    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 on Natty_.  First find out the
+latest binary package versions that are available::
+
+    $ rmadison initscripts | grep natty
+    initscripts | 2.87dsf-4ubuntu19 |         natty | amd64, i386
+
+Then determine the source package corresponding to this binary package::
+
+    $ apt-cache show initscripts | grep ^Source:
+    Source: sysvinit
+
+Find the latest tag added by the package importer::
+
+    $ bzr log -l 1 ubuntu:sysvinit | grep ^tags:
+    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.
+
+
+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 foobar
+
+
+Getting the trunk branch
+------------------------
+
+We use the `bzr branch` command to create a local branch of the package.
+We'll name the target directory `natty` just to keep things easy to remember::
+
+    $ bzr branch ubuntu:tomboy natty
+
+The `natty` directory represents the version of Tomboy in Natty, and you can
+always ``cd`` into this directory and do a `bzr pull` to get any future
+updates.
+
+
+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 pocket in 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 new-package
+    $ 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

=== added file 'udd-latest.rst'
--- udd-latest.rst	1970-01-01 00:00:00 +0000
+++ udd-latest.rst	2011-02-05 01:46:53 +0000
@@ -0,0 +1,46 @@
+==================
+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.
+
+
+Updating your main branch
+=========================
+
+Updating your copy of a branch that corresponds to the package in a particular
+release is very simple, simply use `bzr pull` from the appropriate directory::
+
+    $ cd tomboy/natty
+    $ bzr pull
+
+This works wherever you have a checkout of a branch, so it will work for
+things like branches of `maverick`, `hardy-proposed`, etc.
+
+
+Getting the latest in to your working branches
+==============================================
+
+Once you have updated your copy of a distroseries branch, then you may want to
+merge this in to your working branches as well, so that they are based on the
+latest code.
+
+You don't have to do this all the time though.  You can work on slightly older
+code with no problems.  The disadvantage would come if you were working on
+some code that someone else changed.  If you are not working on the latest
+version then your changes may not be correct, and may even produce conflicts.
+
+The merge does have to be done at some point though.  The longer it is left,
+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
+have committed your current work first::
+
+    $ cd tomboy/bug-12345
+    $ bzr merge-package ../natty
+
+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`.

=== added file 'udd-merging.rst'
--- udd-merging.rst	1970-01-01 00:00:00 +0000
+++ udd-merging.rst	2011-02-05 01:46:53 +0000
@@ -0,0 +1,111 @@
+=======
+Merging
+=======
+
+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.
+
+The first thing to do is to check that the `package importer`_
+:ref:`hasn't failed <up-to-date>` for the package you're going to work on.
+
+When you are in any branch's working directory then you can merge from
+another.  First check you have no uncommitted changes::
+
+    $ bzr status
+
+If that reports anything then you will either have to commit the changes,
+revert them, or shelve them to come back to later.
+
+
+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::
+
+    $ bzr merge-package lp:debian/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::
+
+    $ 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::
+
+    $ bzr resolve
+    $ bzr conflicts
+
+This will resolve any conflicted files that you fixed, and then tell you what
+else you have to deal with.
+
+Once any conflicts are resolved, and you have made any other changes that you
+need, you will add a new changelog entry, and commit::
+
+    $ dch -i
+    $ debcommit
+
+as described earlier.
+
+However, before you commit, it is always a good thing to check all the Ubuntu
+changes by running::
+
+    $ 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::
+
+    $ bzr tags
+
+After testing and committing the merge, you will need to seek sponsorship or
+upload to the archive in the normal way.
+
+
+Merging a new upstream version
+==============================
+
+When upstream releases a new version (or you want to package a snapshot) then
+you have to merge a tarball into your branch.
+
+This is done using the `bzr merge-upstream` command.  From inside the branch
+that you want to merge to you run something like::
+
+    $ bzr merge-upstream --version 1.2 http://example.org/releases/foobar-1.2.tar.gz
+
+This will download the tarball at the specified URL, and merge it in to your
+branch, automatically adding a `debian/changelog` entry for you.
+
+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.  If you
+point to a `.tar.bz2` or similar tarball then it will recompress it as needed,
+or convert it if you pass it a `.zip` or similar.  If your package is v3
+(quilt) format and so can support `.tar.bz2` upstream tarballs then pass a
+`--v3` option to prevent the repacking (this should be `automatically
+detected`_).
+
+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
+error that the tag for the previous upstream version is not available; the
+merge can't be completed without knowing what base version to merge against.
+To work around this, create a tag in your existing existing repo for the last
+upstream version present there; e.g., if the last Ubuntu release was
+*1.1-0ubuntu3*, create the tag *upstream-1.1* pointing to the bzr revision you
+want to use as the tip of the upstream branch.
+
+
+.. _`package importer`:  http://package-import.ubuntu.com/status/
+.. _Squeeze: http://wiki.debian.org/DebianSqueeze
+.. _`automatically detected`: https://bugs.edge.launchpad.net/bzr-builddeb/+bug/627718

=== added file 'udd-newpackage.rst'
--- udd-newpackage.rst	1970-01-01 00:00:00 +0000
+++ udd-newpackage.rst	2011-02-05 01:46:53 +0000
@@ -0,0 +1,170 @@
+======================
+Building a new package
+======================
+
+Let's say I have an upstream project that is not yet available for Ubuntu.  I
+want to create a package from this project and make it available as a PPA_ so
+that other people can more easily use the code.  This also makes a good first
+step in contributing your package to universe_.
+
+
+Example package
+===============
+
+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.)
+
+Because we want to package the trunk branch, getting started is pretty
+simple::
+
+    $ bzr init-repo flufl.enum
+    $ cd flufl.enum
+    $ bzr branch lp:flufl.enum trunk
+    $ bzr branch trunk debianize
+    $ cd debianize
+
+
+Bootstrapping
+=============
+
+You need to get the initial ``debian`` directory created somehow, along with
+all the expected files inside that.  There are many ways to bootstrap that,
+and hopefully there will eventually be `some convergence`_ in the methods,
+especially if you're building standard Python setuptools-based libraries and
+applications.
+
+
+The bzr-builddeb way
+--------------------
+
+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::
+
+    $ bzr dh-make PKGNAME VERSION DOWNLOADURL
+    $ bzr add debian
+
+If you don't have a URL to download a tarball from, you'll need to create the
+tarball locally first.  Use ``bzr dh-make --help`` for details on this command.
+
+After you've created the ``debian`` directory template, be sure to ``bzr rm``
+any ``debian`` files you don't need (e.g. the ``*.ex`` files), and edit files
+such as ``debian/control``, ``debian/watch``, ``debian/copyright`` and
+``debian/changelog``.  The following section may give you some hints about
+that.
+
+
+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
+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!
+
+In either case, start by putting this in your ``~/.pydistutils.cfg`` file::
+
+    [global]
+    command.packages:stdeb.command
+
+
+Modern stdeb
+~~~~~~~~~~~~
+
+Here's how easy it is::
+
+    $ python setup.py debianize
+    $ bzr add debian
+    $ bzr commit -m'Debianize'
+
+We also need a ``debian/copyright`` file.  Normally, we'd use ``dh_make -c``
+for that but again, that doesn't play nicely with UDD.  ``dh_make`` expects a
+particular file system layout that we don't have.  No matter, we'll add the
+copyright file manually::
+
+    $ cp /usr/share/debhelper/dh_make/licenses/lgpl3 debian/copyright
+    $ edit debian/copyright
+    $ bzr add debian/copyright
+    $ bzr commit -m'Added copyright file'
+
+
+stdeb <= 0.5.1
+~~~~~~~~~~~~~~
+
+If you have an older version of stdeb, use this command to create the basic
+``debian/`` directory layout::
+
+    $ python setup.py sdist_dsc
+
+This command leaves you with a ``deb_dist`` directory containing a
+``flufl.enum_3.0.1`` directory.  Inside that is your ``debian/`` directory.
+Because we're using UDD we don't care about anything else that ``sdist_dsc``
+produces, so we can shuffle things around and remove the cruft.
+
+    $ mv deb_dist/munepy-2.0.1/debian .
+    $ rm -rf deb_dist
+    $ bzr add debian
+    $ bzr commit -m'Add debian directory'
+
+
+pkgme
+-----
+
+pkgme_ is a new tool that makes it easy to Debianize a new package.  TBD:
+describe how to use it.
+
+
+debian/control file
+===================
+
+You probably want to edit the ``debian/control`` file at this point, adding
+any information that's missing, or fixing incorrect default information.  For
+example, I needed to modify the ``Maintainer`` and ``Description`` fields, and
+add ``X-Python-Version`` and ``Homepage`` fields.
+
+Now we want to build the source package.  The easiest way to do that is with
+the ``bzr-builddeb`` plugin, however this requires a valid ``debian/watch``
+file so that builddeb can find the upstream tarball.  This really should match
+the version of the checkout you've made.
+
+
+debian/watch file
+=================
+
+Here for example is the ``debian/watch`` file I'm using::
+
+    version=3
+    http://pypi.python.org/packages/source/f/flufl.enum/flufl.enum-(.*).tar.gz
+
+If your tarballs live on Launchpad, the ``debian/watch`` file is a little more
+complicated (see `Question 21146`_ and `Bug 231797`_ for why this is).  In
+that case, use something like::
+
+    version=3
+    https://launchpad.net/flufl.enum/+download http://launchpad.net/flufl.enum/.*/flufl.enum-(.+).tar.gz
+
+So, then it's a matter of...::
+
+    $ bzr add debian/watch
+    $ bzr commit -m'added debian/watch file'
+
+
+Building the source package
+===========================
+
+Now we can build the source package and publish the package as we normally
+would, with ``bzr bd -S`` and ``dput``.
+
+
+.. _PPA: https://help.launchpad.net/Packaging/PPA
+.. _universe: https://wiki.ubuntu.com/MOTU/GettingStarted
+.. _`flufl.enum`: http://launchpad.net/flufl.enum
+.. _`some convergence`: http://launchpad.net/bugs/545361
+.. _stdeb: http://packages.ubuntu.com/lucid/python-stdeb
+.. _`upstream home`: http://github.com/astraw/stdeb#the-commands
+.. _pkgme: https://launchpad.net/pkgme
+.. _`Question 21146`: https://answers.launchpad.net/launchpad/+question/21146
+.. _`Bug 231797`: https://launchpad.net/bugs/231797

=== added file 'udd-patchsys.rst'
--- udd-patchsys.rst	1970-01-01 00:00:00 +0000
+++ udd-patchsys.rst	2011-02-05 01:46:53 +0000
@@ -0,0 +1,190 @@
+===========================
+Working with a patch system
+===========================
+
+Many existing packages that have changes from upstream express those changes
+using a `patch system`_, of which there are several to choose from.  Usually,
+when you make an additional change to a package, you'll want to add a patch
+file to the patch system being used, rather than editing the source code in
+place.  Note however that it is considered bad practice to add a patch system
+to a package that does not already have one.  In that case, either coordinate
+with the Debian maintainer, or edit the files in place.  You can find out if
+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.
+
+Here are some guidelines that I've found helpful.  Clearly the existing tools
+can be improved, but for now this seems to work well enough.  This assumes
+you're using looms to develop your patch, and that the package itself uses the
+quilt_ patch system.
+
+One important thing to know: all source branches reflect the tree after a
+``quilt push -a``.  In other words, when you branch a source branch, you get
+the tree with all patches applied, ready for you to jump right into hacking.
+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!
+
+
+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
+    $ 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.
+
+
+Gotchas
+=======
+
+One thing to keep in mind is that quilt uses a hidden ``.pc`` directory to
+record its status.  This directory is under version control in all source
+branches.  *Watch out* for changes to the ``.pc`` directory that are unrelated
+(or more accurately, uninteresting) to your patch.  This can happen because
+the UDD source branch importer `currently includes any existing .pc
+directory`_ in the imported branch.  This can cause conflicts, or other
+unwanted or unknown changes because you've essentially got two conflicting
+version control systems competing for the same thing (i.e. bzr and quilt3).
+For now, the best recommendation is to revert any changes to the ``.pc``
+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
+==========
+
+``edit-patch`` is a nice little wrapper script that comes as part of the
+``ubuntu-dev-tools`` package.  It pretty much hides the nasty details of
+dealing with the patch system specifically.  For example, while the above
+works well if your package is using quilt already, you'll have to adjust the
+workflow, perhaps significantly, to work with `a different patch system`_.  In
+theory ``edit-patch`` should solve this, but there are currently two blockers.
+
+  * 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.
+  * 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.
+
+
+.. _`patch system`: https://wiki.ubuntu.com/DistributedDevelopment/Documentation/PatchSystem/PackagingGuide/PatchSystems
+.. _`Bazaar looms`: https://launchpad.net/bzr-loom
+.. _quilt: http://www.wzdftpd.net/blog/index.php?2008/02/05/3-quilt-a-patch-management-system-how-to-survive-with-many-patches
+.. _`currently includes any existing .pc directory`: https://bugs.launchpad.net/udd/+bug/672740
+.. _`a different patch system`: http://wiki.debian.org/debian/patches
+.. _`a bug`: https://launchpad.net/bugs/620721

=== added file 'udd-sponsorship.rst'
--- udd-sponsorship.rst	1970-01-01 00:00:00 +0000
+++ udd-sponsorship.rst	2011-02-05 01:46:53 +0000
@@ -0,0 +1,97 @@
+==============================
+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
+have upload rights yourself.  Of course, if you don't have upload rights, you
+will need to seek sponsorship.
+
+Once you are happy with your fix, and have a branch ready to go, the following
+steps can be used to publish your branch on Launchpad, link it to the bug
+issue, and create a *merge proposal* for others to review, and sponsors to
+upload.
+
+
+Pushing to Launchpad
+====================
+
+We previously showed you how to :ref:`link your branch to the bug
+<link-via-changelog>` using ``dch`` and ``debcommit``.  However, the branch
+and bug don't actually get linked until you push the branch to Launchpad.
+
+It is not critical to have a link to a bug for every change you make,
+but if you are fixing reported bugs then linking to them will be useful.
+
+The general form of the URL you should push your branch to is::
+
+    lp:~<user-id>/ubuntu/<distroseries>/<package>/bug-12345
+
+For example, to push your fix for bug 12345 in the Tomboy package for Natty,
+you'd use::
+
+    $ bzr push lp:~subgenius/ubuntu/natty/tomboy/bug-12345
+
+The last component of the path is actually arbitrary; it's up to you to pick
+something meaningful.
+
+However, this usually isn't enough to get Ubuntu developers to review and
+sponsor your change.  You should next submit a *merge proposal*.
+
+To do this open the bug page in a browser, e.g.::
+
+    $ bzr lp-open
+
+if that fails, then you can use
+
+    $ xdg-open https://code.launchpad.net/~subgenius/ubuntu/natty/tomboy/bug-12345
+
+where most of the URL matches what you used for `bzr push`.  On this page,
+you'll see a link that says *Propose for merging into another branch*.  Type
+in an explanation of your change in the *Initial Comment* box.  Lastly, click
+*Propose Merge* to complete the process.
+
+Merge proposals to package source branches will automatically subscribe the
+`~ubuntu-branches` team, which should be enough to reach an Ubuntu developer
+who can review and sponsor your package change.
+
+
+Generating a debdiff
+====================
+
+As noted above, some sponsors still prefer reviewing a *debdiff* attached to
+bug reports instead of a merge proposal.  If you're requested to include a
+debdiff, you can generate one like this (from inside your `bug-12345`
+branch)::
+
+    $ bzr diff -rbranch:../natty
+
+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.
+
+
+Dealing with feedback from sponsors
+===================================
+
+If a sponsor reviews your branch and asks you to change something, you can do
+this fairly easily.  Simply go to the branch that you were working in before,
+make the changes requested, and then commit::
+
+    $ 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::
+
+    $ 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.
+
+Note that if you are sponsored via debdiff attached to a bug report you need
+to manually update by generating a new diff and attaching that to the bug
+report.

=== added file 'udd-uploading.rst'
--- udd-uploading.rst	1970-01-01 00:00:00 +0000
+++ udd-uploading.rst	2011-02-05 01:46:53 +0000
@@ -0,0 +1,120 @@
+===================
+Uploading a package
+===================
+
+Once your merge proposal is reviewed and approved, you will want to upload
+your package, either to the archive (if you have permission) or to your
+*`Personal Package Archive`_* (PPA).  You might also want to do an upload if
+you are sponsoring someone else's changes.
+
+
+Uploading a change made by you
+==============================
+
+When you have a branch with a change that you would like to upload you need to
+get that change back on to the main source branch, build a source package, and
+then upload it.
+
+First, you need to check that you have the latest version of the package in
+your checkout of the development package::
+
+    $ cd tomboy/natty
+    $ bzr pull
+
+This pulls in any changes that may have been committed while you were working
+on your fix.  From here, you have several options.  If the changes on the
+trunk are large, and it will take a while to merge them and test the package,
+then you can merge them back into your working branch to do this.  If not,
+then you can carry on merging your working branch to the main one.  You'll
+want to use the Bazaar ``merge-package`` command rather than just ``merge``::
+
+    $ 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
+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.
+
+The next step is to build and test the modified source package as you normally
+would.  Once you are happy with the upload then you should `dput` the
+source package.  For example, if you want to upload your changes to your PPA,
+then you'd do::
+
+    $ dput ppa:imasponsor/myppa tomboy_1.5.2-1ubuntu5.dsc
+
+You might want to do one more `bzr commit` to make sure all your changes are
+committed in your working tree.
+
+The last step is to mark the change as being the same as the source package
+that was uploaded, so run::
+
+    $ bzr mark-uploaded
+
+This also tells the package importer that what is in the Bazaar branch is the
+same as in the archive.
+
+Now you can push the changes back to Launchpad::
+
+    $ bzr push ubuntu:tomboy
+
+(Change the destination if you are uploading an SRU or similar.)
+
+You are now free to delete your feature branch, as it is merged, and can
+be re-downloaded from Launchpad if needed.
+
+
+Sponsoring a change
+===================
+
+Sponsoring someone else's change is just like the above procedure, but instead
+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
+
+The difference would be that if there are lots of merge conflicts then you
+would probably want to ask the contributor to fix them up.  To do that see the
+next section.
+
+
+Canceling an upload
+===================
+
+At any time before you `dput` the source package you can decide to cancel an
+upload and revert the changes::
+
+    $ bzr revert
+
+You can do this if you notice something needs more work, or if you would like
+to ask the contributor to fix up conflicts when sponsoring something.
+
+
+Sponsoring something and making your own changes
+================================================
+
+If you are going to sponsor someone's work, but you would like to roll it up
+with some changes of your own then you can merge their work in to a separate
+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
+package.
+
+If you don't have an existing branch, but you know you would like to make
+changes based on what the contributor provides then you should start by
+grabbing their branch::
+
+    $ bzr branch lp:~subgenius/ubuntu/natty/tomboy/bug-12345
+
+then work in this new branch, and then merge it in to the main one and upload
+as if it was your own work.  The contributor will still be mentioned in the
+changelog, and Bazaar will correctly attribute the changes they made to them.
+
+.. _`Personal Package Archive`: https://help.launchpad.net/Packaging/PPA

=== added file 'udd-working.rst'
--- udd-working.rst	1970-01-01 00:00:00 +0000
+++ udd-working.rst	2011-02-05 01:46:53 +0000
@@ -0,0 +1,110 @@
+====================
+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
+want to base your branch off the package source branch for the distro release
+that you plan to upload to.  Usually this is the current development release,
+but it may be older releases if you're backporting to an SRU for example.
+
+
+Branching for a change
+======================
+
+The first thing to do is to make sure your source package branch is
+up-to-date.  It will be if you just checked it out, otherwise do this::
+
+    $ cd natty
+    $ bzr pull
+
+Any updates to the package that have uploaded since your checkout will now be
+pulled in.  You do not want to make changes to this branch.  Instead, create a
+branch that will contain just the changes you're going to make.  Let's say you
+want to fix bug 12345 for the Tomboy project.  When you're in the shared
+repository you previously created for Tomboy, you can create your bug fix
+branch like this::
+
+    $ bzr branch natty bug-12345
+    $ cd bug-12345
+
+Now you can do all my work in the `bug-12345` directory.  You make changes
+there as necessary, committing as you go along.  This is just like doing any
+kind of software development with Bazaar.  You can make intermediate commits
+as often as you like, and when your changes are finished, you will use the
+standard `dch` command (from the `devscripts` package)::
+
+    $ dch -i
+
+This will drop you in an editor to add an entry to the `debian/changelog`
+file.
+
+.. _link-via-changelog:
+
+Here's where things diverge a little from typical Bazaar usage.  When you
+added your `debian/changelog` entry, you should have included a bug fix tag
+that indicated which Launchpad bug issue you're fixing.  The format of this
+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
+like::
+
+    tomboy (1.5.2-1ubuntu5) natty; urgency=low
+
+        * Don't fubar the frobnicator. (LP: #12345)
+
+     -- Bob Dobbs <subgenius@xxxxxxxxxxx>  Mon, 10 Jan 2011 16:10:01 -0500
+
+Normally, when you want to commit changes to your branch, you just use ``bzr
+commit``, but in the case where you've made a change to ``debian/changelog``,
+you'll want to use the ``debcommit`` command instead::
+
+    $ debcommit
+
+The reason to use ``debcommit`` instead is that it automatically includes your
+``debian/changelog`` entry in the commit message, and it also adds the
+necessary metadata to link your branch to the bug report when you push your
+branch to Launchpad.  You can do that manually with ``bzr commit`` (and
+eventually, ``bzr commit`` may get smart enough to do it for you), but for now
+``debcommit`` is the most convenient way to do it.
+
+
+Building the package
+====================
+
+Along the way, you'll want to build your branch so that you can test it to
+make sure it does actually fix the bug.
+
+In order to build the package you can use the `bzr builddeb` command from
+the `bzr-builddeb` package.  You can build a source package with::
+
+    $ bzr bd -S
+
+(`bd` is an alias for `builddeb`.)  You can leave the package unsigned by
+appending `-- -uc -us` to the command.
+
+It is also possible to use your normal tools, as long as they are able to
+strip the .bzr directories from the package, e.g.::
+
+    $ debuild -i -I
+
+If you ever see an error related to trying to build a native package without a
+tarball, check to see if there is a `.bzr-builddeb/default.conf` file
+erroneously specifying the package as native.  If the changelog version has a
+dash in it, then it's not a native package, so remove the configuration file.
+Note that while `bzr bd` has a `--native` switch, it does not have a
+`--no-native` switch.
+
+You might also see an error that looks something like this:
+
+    dpkg-source: error: Version number suggests Ubuntu changes, but
+    Maintainer: does not have Ubuntu address
+
+In a sense, this is a safeguard to ensure that ``update-maintainer`` is run
+when necessary.  However in this case, you can just temporarily set the
+``$DEBEMAIL`` environment variable to a non-@xxxxxxxxxx address::
+
+    $ DEBEMAIL='me@xxxxxxxxxxx' bzr bd -S
+
+Once you've got the source package, you can build it as normal with
+``pbuilder`` or ``sbuild``.