Summary

This page describes how the version tracking on bugs.debian.org works, and what needs to be fixed in it.

Status changes

Command to control@bugs.d.o

Command

After the command/mail

State

FoundVersions

FixedVersions

mail to -done

done

+version

close version

done

+version

reopen

open

clear field

reassign package

clear field

clear field

found

see [1]

+version

-version

notfound

-version

fixed

-version

+version

notfixed

-version

[1]: If the found version is greater than or equal to the greatest fixed version, or the found causes the "fixed" list to be empty, the bug is reopened.

Tutorial

Originally based on my (me = ?SteinarGunderson) posts to Planet Debian. Please edit as you see fit for the wiki format.

Part 1

As I've received feedback that this topic is hard, I'm going to split it into several pieces. This is piece one, out of four. It contains the very, bare minimum; if you're not really interested, or think this bug tracking stuff is just horribly difficult, here's the deal:

Part 2

The Debian BTS attempts to track what version of a given package a given bug applies to -- this is important to know if and where it needs fixing, and recently also for migration to testing.

First, note that not all bugs should be versioned. For instance, if a bug is not-a-bug (say, it was all a misunderstanding on the user's parts), it should just be closed the regular way, without a version (just send a message to NNNN-done@bugs.debian.org with the reason). However, almost all bugs that required a change in your (source) package can and should be versioned, as explained below.

The basis of it all is the BTS' idea of the versioning tree. Every package version has (at least in the BTS world) one distinct ancestor, or zero if it's the very first version. This is extracted from the changelogs as the package is uploaded, so make sure your changelog actually reflects reality. [1] If you look at a bug in the web interface, you will see the relevant part of the version tree (in the upper right corner); click on it and you'll be able to see the entire tree (use the "don't ignore boring" option). Just look at it for a few bugs in your packages -- it makes the entire process much easier to understand, and it should hopefully over time give you a sort of intuition about how the entire thing works.

[1]: Note that this means merging a package that has branched is not supported. If you're merging two different branches of your packaging (say, a security fix from stable into your unstable package), the BTS will pick the uppermost ancestor in the changelog as the sole ancestor. In this case, you will need to manually clean up the situation yourself. This does not happen very often to most people, though.

Part 3

(Or: We aren't in Kansas anymore! :-) )

This is the third part of my attempt to explain Debian bug versioning. The first and second parts were posted yesterday and the day before that; read them first if you haven't already.

In the past, all bugs had a "status" field, which was either "open" or "done". Although it still exists, and you can view and manipulate it, the status is completely irrelevant when dealing with versioned bugs.[1] Instead, all bugs have a found list and a fixed list, containing package versions. (One or both of these might be empty.) Together with the version tree (which belongs to the package), they determine if a given version is considered as containing a given bug or not.[2] The logic for this is pretty obvious: If B descends from A and A is buggy, B is also buggy (unless the bug is fixed in B). All the lists can contain multiple versions, since a bug could have appeared independently in multiple branches, or be fixed and then for some reason resurfaced.

You normally need not fiddle with the lists; when you open a new bug, the "found" list will be initialized with whatever version you reported the bug against, and when you close it in a package upload, that version will be added to the "fixed" list. However, if you need to, you can add or remove stuff from the "found" list with the "found" and "notfound" control@ commands, and add or remove stuff from the "fixed" list with the "fixed" and "notfixed" control@ commands.[3] Note that the preferred way of closing bugs, at least the first time, still is sending a message to NNNN-done@bugs.debian.org, but your message pseudo-header needs to include a "Version:" field to get the right version in the "fixed" list. If you close the bug in the changelog, this is done automatically for you.

I'll repeat that once more, since you probably dozed off at this point: If you report bugs with reportbug and close them in the changelog, everything will be alright automatically. (Well, there are corner cases, but usually it will.)

That pretty much wraps up part 3 and the general understanding of the system. Part 4 is just going to fix some leftovers.

[1]: An "unversioned bug" in this context is one where the fixed list is empty. Almost all bugs (except bugs against pseudo-packages) would have at least one version in the "found" list, since that comes from the initial bug submission.

[2]: Actually, the BTS also distinguishes between "fixed" and "absent": If a bug tree goes version 1,2,3,4, and a bug is found in 2 and fixed in 3, it will be "fixed" in 4 but "absent" in 1. The distinction is, however, irrelevant for most end users, so you can largely just ignore it.

[3]: "notfound" does not manipulate the "fixed" list -- it only removes stuff from the "found" list. This can be confusing at first. Just remember that the commands manipulate the lists, not the bug itself.

Part 4

These are only a few loose ends that I intend to pick up in this part:

So, remember, use that version graph whenever you're confused, and have fun! (As if bugs are fun. :-) )