oracular (3) Debbugs::Versions.3pm.gz
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.