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.