NAME¶

Debbugs::Versions - debbugs version information processing

DESCRIPTION¶

The Debbugs::Versions module provides generic support functions for the implementation of version tracking in debbugs.

Complex organizations, such as Debian, require the tracking of bugs in multiple versions of packages. The versioning scheme is frequently branched: for example, a security update announced by an upstream developer will be packaged as-is for the unstable distribution while a minimal backport is made to the stable distribution. In order to report properly on the bugs open in each distribution, debbugs must be aware of the structure of the version tree for each package.

Gathering the version data is beyond the scope of this module: in the case of Debian it is carried out by mechanical analysis of package changelogs. Debbugs::Versions takes version data for a package generated by this or any other means, merges it into a tree structure, and allows the user to perform queries based on supplied data about the versions in which bugs have been found and the versions in which they have been fixed.

DATA FORMAT¶

The data format looks like this (backslashes are not actually there, and indicate continuation lines):

  1.5.4 1.5.0 1.5-iwj.0.4 1.5-iwj.0.3 1.5-iwj.0.2 1.5-iwj.0.1 1.4.0 1.3.14 \
        1.3.13 1.3.12 1.3.11 1.3.10 ...
  1.4.1.6 1.4.1.5 1.4.1.4 1.4.1.3 1.4.1.2 1.4.1.1 1.4.1 1.4.0.31 1.4.0.30 \
        1.4.0.29 1.4.0.28 1.4.0.27 1.4.0.26.0.1 1.4.0.26 1.4.0.25 1.4.0.24 \
        1.4.0.23.2 1.4.0.23.1 1.4.0.23 1.4.0.22 1.4.0.21 1.4.0.20 1.4.0.19 \
        1.4.0.18 1.4.0.17 1.4.0.16 1.4.0.15 1.4.0.14 1.4.0.13 1.4.0.12 \
        1.4.0.11 1.4.0.10 1.4.0.9 1.4.0.8 1.4.0.7 1.4.0.6 1.4.0.5 1.4.0.4 \
        1.4.0.3 1.4.0.2 1.4.0.1 1.4.0 \
  1.4.0.35 1.4.0.34 1.4.0.33 1.4.0.32 1.4.0.31

METHODS¶

new

Constructs a Debbugs::Versions object. The argument is a reference to a version comparison function, which must be usable by Perl's built-in "sort" function.

isancestor

Takes two arguments, "ancestor" and "descendant". Returns true if and only if "ancestor" is a version on which "descendant" is based according to the version data supplied to this object. (As a degenerate case, this relation is reflexive: a version is considered to be an ancestor of itself.)

This method is expected mainly to be used internally by the "merge" method.

leaves

Find the leaves of the version tree, i.e. those versions with no descendants.

This method is mainly for internal use.

merge

Merges one branch of version data into this object. This branch takes the form of a list of versions, each of which is to be considered as based on the next in the list.

load

Loads version data from the filehandle passed as the argument. Each line of input is expected to represent one branch, with versions separated by whitespace.

save

Outputs the version tree represented by this object to the filehandle passed as the argument. The format is the same as that expected by the "load" method.

buggy

Takes three arguments, "version", "found", and "fixed". Returns true if and only if "version" is based on or equal to a version in the list referenced by "found", and not based on or equal to one referenced by "fixed".

"buggy" attempts to cope with found and fixed versions not in the version tree by simply checking whether any fixed versions are recorded in the event that nothing is known about any of the found versions.

allstates

Takes two arguments, "found" and "fixed", which are interpreted as in "buggy". Efficiently returns the state of the bug at every known version, in the form of a hash from versions to states (as returned by "buggy"). If you pass a third argument, "interested", this method will stop after determining the state of the bug at all the versions listed therein.

Whether this is faster than calling "buggy" for each version you're interested in is not altogether clear, and depends rather strongly on the number of known and interested versions.