https://blueprints.edge.launchpad.net/bzr-builddeb/+spec/package-revisionspec

Overview

In order to refer to the revision that corresponds to a particular package version more easily a revisionspec should be provided.

Each upload is tagged with a known that that contain the version number, so given a version number the corresponding revision can be easily found.

Single distribution case

When there is only a single distribution to consider it is easy.

UI

The "package:" revisionspec will be used. Some examples:

   # cat debian/control from the 0.1-1 version of the package
   bzr cat -r package:0.1-1 debian/control

   # show the differences between version 0.1-1 and 0.1-2 of the package
   bzr diff -r package:0.1-1..package:0.1-2

   # We get an error when we ask for a version of the package that is not known
   bzr log -r package:1233-1
   bzr: ERROR: Unknown version: 1233-1

Design

Given a version number the appropriate tag can be looked up, and if found that revision used. If it is not found then an error can be given.

Multiple distribution case

When there are multiple distributions to consider things are more complicated, as we don't assume that packages with the same version number are identical across distributions.

UI

We want the simple case to still be as easy as in the single distribution case, so where there is no ambiguity we will accept just a version number.

   bzr log -r package:0.1-1ubuntu1

However, if this version number occurs in multiple distributions there will be an error

   bzr log -r package:0.1-1
   bzr: ERROR: Ambiguous version '0.1-1', please specify a distribution.

The user can then disambiguate

   bzr log -r package:0.1-1:debian

Design

When a distribution is specified we can just look up the tag corresponding to the version and distribution.

When just a version number is specified we look up tags corresponding to all known distributions. If none are found then raise an error stating that the version is unkown. If more than one are found we ask the user to specify the distribution. If exactly one is found then there is no ambiguity, and we use that revision.

It may also be desired to allow the user to switch the order of the arguments in the revisionspec, i.e. make "-r package:debian:0.1-1" valid. This should work well, as long as a package doesn't use "debian", "ubuntu" or similar for its version number.

Discussion

There are a number of issues with allowing the user to omit the distribution.

1. We must maintain a list of all known distributions, so if any other distro wants to make use of the tools they must ask to be included in the list.
2. Ambiguity may appear over time. If one user posts instructions assuming that a version will not be ambiguous, and then an upload is done which makes the version ambiguous then other people following the instructions may be confused.
3. A sync where a package has been directly uploaded to the syncing distribution at an earlier point will create ambiguity under this scheme, where the user will not consider it ambiguous. There are a couple of possible solutions.
   1. Use a revision property to mark syncs, so that this can be avoided. Perhaps requires special tool to sync. Possibly bad failure mode.
   2. Test tree equality when ambiguity is found. This will cause a performance hit, but may be acceptable due to making it easier for users, and the fact that it doesn't hit every use of the revisionspec.

Allowing a blank revisionspec

bzr allows the revisionspec to be empty, i.e. "-r package:" is valid from bzr's point of view. It may be possible to make use of this to make things easier for the user.

The obvious use seems to be specifying the last version, so if you wanted to see the changes that this upload would introduce you would do "bzr diff -r package:".

The difficulty is deciding what "last" means here. There are a few possibilities.

Using the changelog

debian/changelog could be read, and the first version that doesn't have "UNRELEASED" as a distribution could be used. This isn't great as it requires discipline in maintaining the "UNRELEASED" tag, and fails when you want to do the final diff after finishing the changelog for an upload.

The rule could be the first version without "UNRELEASED", and if there is no version with "UNRELEASED" then use the second version. This instead requires adding a changelog stanza as the first thing you do.

Using the changelog entry is also perhaps not right during syncs, as some entries are thrown away.

During merges the reordering of the changelog may mean that you don't get the revision that you want.

If what the user wants from this feature is "the version currently in the archive" then perhaps the next one is correct.

Use apt_pkg to retrieve the version currently in the archive

I think the user will often want to diff against what is currently in the archive.

Looking this up directly with apt_pkg is possible. However it suffers from delays, as it takes time for an upload to appear on the mirrors, and then in a user's cache via an "apt-get update".

Use the ancestry

It would be possible to define an algorithm to walk the ancestry of the package and pick a version from there. This is easy to do when there is a version that dominates all others, but in the presence of merges it's hard to know what version the user would like.

Allowing the version to be blank

Related to the last point, it would be good to allow "-r package:debian" and similar to refer to the last version in that distribution. There are many of the same problems as the last section though.

Using this method but erroring when there is not one clear version that the user would want would also be possible.