Ubuntu Wiki

Status

• See https://launchpad.net/distros/ubuntu/+spec/developer-documentation

Summary

We should have well-organized developer-oriented documentation for our various tools and procedures, including freeze exceptions, merge-o-matic, seeds and their germination, and much, much more.

Use cases

Alexander wants to help to translate his favorite application "hello" to his native Bohemian, but he doesn't know anything about where to start and where to look.

Barbie wants to become a Universe Developer (MOTU) but she doesn't know how to start to work on a Debian-format package.

Camilla has just started as a new Canonical staff member working on Ubuntu and is lost in a maze of twisty incomplete wiki pages trying to figure out how Ubuntu's processes are supposed to work.

Approach

We have concluded that the best way to achieve this would be to:

Create an Ubuntu Developers' Reference, which would be derived in the usual way (with a ubuntuNN version etc.) from the Debian Developers' Reference.

As well as deleting or replacing Debian-specific content from the DDR, we will transfer content from process-related wiki.ubuntu.com pages and add additional information as seems relevant.

The Ubuntu Documentation Team will of course be consulted, but the UDR will be maintained primarily by Ubuntu developers since (a) much of the proposed (non-Debian) content is currently known only to Ubuntu developers and (b) the audience consists of Ubuntu developers.

The UDR should be kept up to date as processes change.

Content

The list below is a list of topics to cover and a sketch of the content for each one. The organisation of the content will be that from the DDR, with appropriate additions, so not necessarily in the order listed here.

In many cases the exact details of the information to be included will need to be discovered by the UDR author by trawling the wiki and/or asking around eg on IRC.

Specific topics and processes to cover

The top of the UDR will say which Ubuntu release the document relates to, and how to find versions for other releases (so that it is straightforward to have different process documents for eg breezy vs. dapper)

The UDR will document when and how to make ftp-master requests including syncs and package removals, including how to contact the ftp-masters.

The method used to determine the set of packages included in main and on the CDs will be documented including documentation about seeds and germination (with references to the appropriate revision control branches and germinate output logs).

We will say who to talk to to decide whether to make a particular change/upload: that you should usually just go ahead and make change covered by own area of responsibility (which may be a package, or some cross-package property), and that for other things it's probably best to ask someone. We'll explain how to find out who last touched a package. The UDR will warn about what to do for changes that may cause compatibility problems or require corresponding changes to other packages.

In particular, we will say who is responsible for various important subsystems, including at least the following:

• kernel team, #ubuntu-kernel
• docs team, #ubuntu-docs
• universe packages, #ubuntu-motu

If you need advice, input or permission, the UDR will give you an idea of who to contact, or at least how to find out who to contact.

There will be information about freezes including who to contact about freeze exceptions, and reference will be made to BreezyReleaseSchedule (and successors).

We will describe what you should do after uploading, including where (if anywhere) to send copies of your patch, and what emails to expect and logs to check to see that all went well.

We will explain how to handle bugs, either by referring to the bug handling practices wiki page or preferably by incorporating the results of that UBZ BOF into the UDR.

There will be some documentation about how to get upload rights, including references to policy documents about registering GPG keys in launchpad, the differences between universe and main, and references to MOTU processes including wiki.ubuntu.com/REVU.

There will be a brief discussion about how we handle translations (in particular how we do it differently to Debian) and a reference to Rosetta and langpack documentation.

There will be some information about Ubuntu backports, including where to find them, some comments about how to be nice to backporters, and information about how to contact the backport team.

Information to be moved from elsewhere

Content should be transferred from DeveloperResources (which should become a navigation page), and the UDR will link to DeveloperResources.

The package introdeveloperdocs (currently awaiting review) contains some not entirely accurate content and should be abandoned/rejected. (Also, it has an incorrect version number for an Ubuntu-native package.)

Information about packaging and uploading

Several topics about the construction of packages need to be covered, including:

The differences in metadata between unmodified Debian source packages, Ubuntu-specific source packages, and Debian packages modified for Ubuntu.

The different approaches to packaging will be covered briefly, including specifically common approaches to constructing debian/rules, such as straightforward construction by-hand, debhelper, and cdbs; we will make some recommendations about when to use and when not to use these particular tools (eg, that most Gnome packages use cdbs).

Patch systems will also be described, and some advice given about whether to use one and which one to use. We will cover dpatch and cdbs at least, as well as reviewing manual approaches.

We will describe how to merge new versions from Debian, upstream or external repositories and discuss merge-o-matic.

There will be a brief discussion of the use of chroots and we'll also briefly mention other useful tools including pbuilder, sudo, lintian/linda and piuparts.

Implementation plan

We will focus on producing a useable UDR (by replacing Debian-specific information in the DDR) as soon as possible.

The resulting draft UDR will be made available to all Ubuntu developers as work proceeds on the additional Ubuntu-specific content.

Where new content is not Ubuntu-specific, we will supply it to the DDR maintainers via the usual Debian channels.

Arrangements will be made for the current versions of the UDR to be given a stable URL, and of course links will be made from appropriate places.