THIS IS A DRAFT
This document provides guidelines for other Ubuntu teams or third parties for integrating new projects and changes of existing projects into Ubuntu. This is done through the Ubuntu Platform team, which is responsible for putting together the Ubuntu releases from all the upstream free software projects.
One major focus of the Platform team is "packaging", which means to take the original software ("upstream"), add control and build scripts to be able to noninteractively build Debian-style software packages ("debs") which can be installed in a standard fashion.
If you are working on new software which should be shipped in Ubuntu, you act as an upstream for the platform team.
Please read UbuntuDevelopment to get a basic understanding of the most important concepts, terminology, and workflows in Ubuntu development.
As upstream, you are responsible for development, primary QA, bug fixing, and releasing your software. Informing the platform team about your plans and releases will make sure that your software gets shipped in Ubuntu in the best way possible.
The platform team will gladly help you with initial packaging, and updating the packaging for major new upstream changes. Keeping an existing packaging up to date is generally much easier, and you might want to do it yourself for e. g. providing nightly PPA builds; this is not a requirement, though.
If you are working closely together with Ubuntu (e. g. you are a team in Canonical), you should take primary responsibility for the packaging and make it available to the platform team (see "Packaging branches" below). Canonical internal upstreams should aim to have a permanent "package maintainer" in the platform team who integrates their work into the distribution.
Developers should be using the latest development release of Ubuntu for their development environment. This ensures that their work is compatible and stays reasonably in sync with Ubuntu. It may be advisable to use a virtual machine or chroot prior to beta.
Please do not hesitate to consult the platform team about any integration question you have, such as our choice of default applications, how your software should interact with other parts of the system, how to store configuration, security aspects, etc.
Start development before the Ubuntu release cycle starts so that you can land your first code drop as early as possible. By way of example, the first development snapshot of GNOME for Ubuntu 8.10 (2.23.1) was made available on the 21st of April: 3 days before the 8.10 cycle even started! We were able to upload it as soon as we were ready, and start finding and fixing integration bugs.
It is recommended that you arrange a one or two hour presentation for the platform team and any significantly involved upstream partners before discussing your plans publicly at a the Ubuntu Developer Summit. Try not to "break news" to the platform team/key upstream partners and the Ubuntu Developer Summit participants simultaneously.
If you have the chance, participate in the Ubuntu Developer Summit. This is your best chance by far to build relationships with the relevant people, agree working practices, and participate in discussions about feature projects.
- You should document your development schedule and share it with the platform team during the early planning phases, so that it can be taken into account when making plans for the Ubuntu release cycle.
- If new features need new dependencies, don't fiddle with local code copies or static linking; talk to the platform team to update/provide the dependency in the development release (and perhaps also as backports to existing stable releases). Eventually this needs to happen anyway.
Integrating new software
You should develop your software in a revision control system. Due to great integration into Launchpad, bzr is the preferred one, but we can deal with many other common systems (git, svn, cvs, ...). Revision control allows other people to collaborate with you in an easy way, and allows the platform team to derive packaging branches, cherrypick changes, and provide changes back to upstream in a smooth way.
Releases of your software should generally be provided as tarballs. If you store your upstream branch on Launchpad in bzr, it is also acceptable (and in fact even easier for packaging) to tag releases and ask the Platform team to use this branch as a source of upstream releases.
Please avoid putting the packaging (the debian/ directory) into the upstream trunk development branch. Instead, provide a separate packaging branch with the debian/ directory added, which you can e. g. use to build packages for testing PPA.
Separating upstream and packaging has several reasons:
- A packaging branch always corresponds to a particular distribution release/archive, e. g. "Ubuntu jaunty", "Ubuntu intrepid-updates", "Debian experimental", or "nightly PPA build". With trunk being the focus of upstream development, this generally does not correspond to any package archive.
Different package branches will always differ from each other. The minimum delta is debian/changelog, but there can be more changes (such as different build dependencies for different releases). All of those should just merge from the upstream trunk, merging from each other generally doesn't make sense or work (cherrypicking works fine, of course).
- Upstream and packaging branches have different owners ("committers"). While you generally own the trunk,
- It allows other distributions to sanely maintain packages, too. E. g. they can branch from trunk and add RPM spec files without constantly resolving conflicts for Debian packaging changes (which they don't have).
- It allows other distributions or contributors to supply branches which you can merge into trunk.
Changing existing software
Ideally your planned changes are discussed with upstream upfront, and get developed directly upstream. At least, consensus should be reached to make sure that they get accepted at some point.
Just writing patches and sending them to the platform team isn't going to be sustainable, since then the platform team has to do the upstreaming and porting to new releases of code which it isn't familiar with. This both delays packaging of new upstream releases, and also doesn't provide any incentive for you to work with upstreams in the first place.
If patches are very intrusive and large, you should create a proper branch from upstream's project and keep it up to date with new upstream releases, and provide that as an upstream source to the platform team. In the specific case of Gnome projects, it is advised to branch off/merge from http://bzr-playground.gnome.org/
If patches are small, it is sufficient to follow the standard contributor best practice to file patches upstream and provide a reference, before they get applied to an Ubuntu package.
PPAs are a great tool to provide packages for a selected set of early testers, as well as for internal use in your project. E. g. they can be used to provide nightly builds, or making newer versions of your software available for older Ubuntu releases.
You should use them as a standard tool to receive as much feedback as possible prior to getting your software (or a newer version of it) into Ubuntu proper.
Having software in a PPA is a great step towards making it available in Ubuntu. However, please be aware that it is not the same as "being in Ubuntu". It is important to keep the software current in the Ubuntu development release as well, where lots of people will provide feedback, and which will be the basis for judgement at feature freeze.
Please be aware that a PPA is generally not visible to the platform team. Do not expect the platform team to look for packages in all PPAs out there and upload them to Ubuntu; you need to contact the platform team about requests for updating packages to a new version (preferably from a bzr branch, or if necessary, from a PPA). Generally, the Technical Lead of the relevant team is a good address for setting up permanent arrangements for this.
If your software contains user-visible strings, they need to be translatable using the standard gettext system, and preferably using intltool for build time translation handling.
There are tutorials on the web. Please feel free to consult Martin Pitt or Arne Goetje about how to design your software to be translatable properly.
The actual translating is a best-effort community task so far, and happens on Launchpad for Ubuntu packages. You can and should use Launchpad for getting upstream translations as well, if you host your project on Launchpad.
Please see TranslationLifecycle for details about how translations are handled in Ubuntu.
The most important dates for upstream contributors are:
Ubuntu Developer Summit: plans for current development release; this specifies which changes to expect for the next release.
FeatureFreeze: No new features, ABI/API changes, new packages, or major changes after this point. Exceptions need to be approved by the release team. This usually happens about two months before the final release.
This day is a reckoning: that is the time when the platform team decides which features will stay, which will receive freeze exceptions, and which will be removed. It is a decidedly bad time to land significant amounts of new code for the first time, because we will not have sufficient information to make a smart decision. The code you drop at feature freeze should be ready for this type of evaluation, i.e. have been in the repository for a while already and be ready for testing by platform developers and ambitious users. It can take some time to get new packages or new versions into the archive,
and they need to land in the archive before feature freeze. This means that if a significant change is not received until feature freeze, it is unlikely to successfully meet the deadline.
Please see the release process for further information.
As a general rule: Release early, release often; do not wait until something is fully developed and land large changes right before Alphas or the FeatureFreeze. It is perfectly reasonable to land incomplete code/features in the development release, as long as they do not cause major regressions or system breakage.
Code submitted for inclusion in the platform should already have been QAed. The platform team will tackle integration issues and work with you to resolve issues which are discovered during public user testing, but you cannot rely on this as your only source of QA. The platform team cannot test your code for you, we can only get it out to users for real-world exposure.
By default, new packages land in Ubuntu's "universe", which is the set of unsupported free software packages. If a package should be officially supported by Canonical and get installed by default, it needs to fulfil the UbuntuMainInclusionRequirements (in particular, QA, internationalization, and maintenance).
The actual main promotion process will be carried out by the platform team, if/when the software was planned to become officially supported in a particular Ubuntu release and a sufficiently mature version is available in universe.
As soon as your software becomes available in Ubuntu, and gets announced, you will start getting bug reports. If you want to closely cooperate with the platform team and keep your software in good shape, you should subscribe to bugs in your package and product. As the upstream, you generally are in the best position to debug and fix problems.
Subscribing to your packages in Ubuntu and handling bugs for them is a firm requirement for Canonical teams providing software for Ubuntu.
If the software itself is correct, but the problem is about the packaging (e. g. the package does not ship some files, fails to install or upgrade, or does not handle renaming of a configuration file), please subscribe your contact point in the platform team to the bug (the Technical Lead of the team is a default point of contact who can help you with finding a proper assignee, or get help for you to fix the problem yourself in your packaging).
Bug handling for software which is developed in Ubuntu
The vast majority of bugs which get filed against Ubuntu packages are usually upstream bugs; this particularly applies to Canonical-internal upstreams, where it is very unlikely that the Ubuntu package has any (significant) patch at all.
So in general it is sufficient to use the Ubuntu bug task as it was filed originally. A working practice is to create an upstream task and set that to fixed once you fixed it in the upstream development trunk, to be able to see which bugs get fixed after the next merging into the Ubuntu package. That's much less work than tentatively creating upstream tasks for all incoming Ubuntu tasks, because then you need to manage every status twice.
In order to minimize overhead, maintaining responsibility should be done through assignees mainly. I. .e if a bug report a packaging problem (package does not install, upgrade, or a particular action for configuring it is not done), it should be assigned to the responsible person in the platform team.
So with regard to triaging and providing a fix, a bug report against an Ubuntu package is very similar to one in classical upstream bug trackers. The significant difference is that the status should reflect the status in Ubuntu, not in your upstream project. In particular, the bug should be closed once the fixed version is uploaded into Ubuntu, not already when you fix the bug in the upstream branch or do a new upstream release. If you want to track this separately, you should add upstream tasks to the Launchpad bug report.
You should discuss how to escalate bugs between your team and the platform team with your platform team contact. The preferred way is to subscribe people to the bug report for questions, and set the assignee field to the person who will work on the fix; this will keep all relevant information in the bug report trail. However, depending on your preference you might also want to use email, IRC, or other means of coordination.
Stable release updates
Bugs which are major regressions or cause data loss get fixed in stable Ubuntu releases. Really trivial and obvious patches generally get accepted, too.
This is primarily because there must be a near-zero incidence of regressions, and full regression testing is usually impractical due to resource constraints. Users also appreciate, and depend upon, the stability of their Ubuntu experience, and should not have it change unexpectedly.
Providing updates for stable Ubuntu releases means that you need to support a particular older version of your software for the lifetime of that Ubuntu release. If you can provide minimal backports of important bug fixes to those stable versions, you will tremendously help the platform team; for non-straightforward backports, they often require your help.
If you think a bug is worth fixing in a stable Ubuntu release, please subscribe ubuntu-sru to the bug report.