ImporterSpecification
This is the specification for the importer part of the Distributed Development effort. The status of the blueprint can be tracked at
Summary
In order to allow some features of a version control system to be used in Ubuntu development, regardless of the package being worked on bzr branches of the history of the uploads to Ubuntu will be made available for every package.
Release Note
None, this should not affect users.
Rationale
For various tasks having the history of the package in a version control system, rather than the source packages, can be much more efficient. Currently only a limited number of packages are available in version control, and there is not one single version control system in use. There are tools such as debcheckout that help to work around the last part, however, you still need to know how to get the information from the particular version control system, and some only version the debian/ directory.
To provide the advantages for all packages, and to make sure the developer can work with the branch that is available then all the history of each package in Ubuntu will be made available in bzr branches.
If supporting tools are then provided it should provide a convenient way to inspect the package history.
Use Cases
Amanda would like to find out in which version, and by whom, a particular line was introduced in to the gcc package. She grabs the gcc branch that is available with a single command, and then uses "bzr gannotate" on the file and quickly finds the revision. She can then see who made the change, and see the change along with its changelog entry and the other changes made in the same package revision.
Kiran and Pete want to work together developing a major change to the packaging of postfix. They each grab the branch from launchpad with a single command and start working. They can then push their changes to personal branches on launchpad, and merge from each other to share their work. When they have completed their work they can upload the package. They can either let the importer take care of updating the package branch (which would lose the granularity of commits they would have made), or push to the package branch and tag it is having been uploaded. If they cannot upload the package themselves then they can get sponsorship, and also ask their sponsor to push to the package branch.
Assumptions
Design
There will be an importer tool written that given a list of source packages will turn those in to two branches. One branch will be the "upstream" branch that is just the ".orig.tar.gz" parts of the source packages extracted in sequence and committed. The second branch will be the "ubuntu" one, which will be the full extracted source packages committed in sequence. There will also be extra parents added to link to the upstream branch where appropriate (first upload with a new upstream version).
These branches will then be made available on launchpad, under a new namespace specifically for source package branches. The exact details of the launchpad side are still being worked out, but we have broad agreement on what it will look like.
For the source package branches:
http://bazaar.launchpad.net/<distro>/<suite>/<package>
e.g.
http://bazaar.launchpad.net/ubuntu/hardy-updates/gcc
there will also be +trunk to refer to the current development release, e.g.
http://bazaar.launchpad.net/ubuntu/+trunk/gcc
Personal branches will still live under ~<user>, but will have a similar form, e.g.
http://bazaar.launchpad.net/~james-w/ubuntu/hardy-updates/gcc/fix-23456
On the bzr client side, and possibly with redirects on launchpad, some of the parts may become optional to save having to remember all the parts.
As well as the initial importer there will be an incremental importer that watches for new versions being published and appends them to the correct branch. This means that the package branches should always be up to date with the archive, perhaps with short delays while the import happens.
The source package branches may be read only for the initial stages of this project. If they are not then the write access control will follow exactly that used for soyuz, so that you can only write to a package branch if you can upload the package. This should prevent anyone trying to abuse the system.
If the branches are not read only then there are two cases of people pushing to the branch that we need to handle. The first is when they are pushing as they upload. We will trust them to push exactly what they upload, with the client side tools helping to ensure that this will be the case (we could check on the server side if there are concerns). The client side tools will indicate to the importer that this is what the developer did, and so prevent the new upload being imported.
The second case is when the developer pushes, but does not upload. There are two concerns with this. One is other people grabbing the branch and thinking that the changes that have been pushed are in the archive when they are not, and the other is someone else uploading the package without integrating the changes. For the former case we may be able to make the tools indicate to the developer when this is happening, but we need to make developers understand that this can happen. For the latter case we can have the importer detect when this is happening.
If the importer detects that this is going to happen it can do one of two things.
- Move the branch off to one side, and then import the new revision on top of the last uploaded one, and then
- mail the developers who had their changes stomped on to let them know and ask them to merge it.
- Simply add the import on to the tip of the branch and again email the developers who had their changes stomped
- on and tell them how to resurrect them (again it's a merge, but it looks slightly differen).
The second has the advantage that it doesn't cause existing branches to diverge, but it does introduce extra revisions in to the history that may confuse someone looking at it. The current preference is for 2.
Implementation
This section should describe a plan of action (the "how") to implement the changes discussed. Could include subsections like:
UI Changes
Should cover changes required to the UI, or specific UI that is required to implement this
Code Changes
Code changes should include an overview of what needs to change, and in some cases even the specific details.
Migration
Include:
- data migration, if any
- redirects from old URLs to new ones, if any
- how users will be pointed to the new way of doing things, if necessary.
Test/Demo Plan
It's important that we are able to test new features, and demonstrate them to users. Use this section to describe a short plan that anybody can follow that demonstrates the feature is working. This can then be used during testing, and to show off after release.
This need not be added or completed until the specification is nearing beta.
Outstanding Issues
This should highlight any issues that should be addressed in further specifications, and not problems with the specification itself; since any specification with problems cannot be approved.
BoF agenda and discussion
Use this section to take notes during the BoF; if you keep it in the approved spec, use it for summarising what was discussed and note any options that were rejected.