Beefy Boxes and Bandwidth Generously Provided by pair Networks
Do you know where your variables are?

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??


Version numbers and dependency specifications are best expressed at the level of the distro (i.e. the atomic unit of installation) rather than at the level of the module.

CPAN authors can emulate distro-level versioning by unifying version numbers across all subcomponents and by treating the removal of a module from a distro as a backwards compatibility break.


Per-module dependency specification

A number of distributions on CPAN provide multiple modules with disparate $VERSION numbers. Take URI 1.60:

    URI:             1.60
    URI::Escape:     3.31
    URI::Heuristic:  4.20
    URI::URL:        5.04

The CPAN toolchain supports expressing dependencies at the level of individual modules...

        URI::Escape: 3.31

... though it is common to use only the primary module in the distro as a proxy for all the others:

        URI: 1.60   # may be a proxy for URI::Escape 3.31

Impracticality of consistent per-module dependency specification

In theory, it is safest for downstream users to express all module dependencies individually, because individual dependency specs will continue to resolve properly if a module moves to a different distribution -- for example, if URI::Escape were to be broken out of URI.

However, there are numerous distributions out there which are structured as large collections of small modules, and for which it would be tedious and error-prone to specify each constituent dependency seperately. The existence of such distributions renders strict per-module dependency specification impractical.

Removing a module from a distro breaks backwards compatibility

The only safe assumption for an author to make is that some fraction of the user base has listed the primary module of a distro as a dependency when they really want a different module within the distro. Users in this category are going to get burnt when their desired module gets removed. Therefore, removing a module from a distro must be classified as a compatibility break.

Hidden major version breaks

Say that URI::Escape makes a major version increment, but URI does not:

URI         1.60 ... 1.61
URI::Escape 3.31 ... 4.00

The distribution's version number only moves from 1.60 to 1.61 because is tied to the URI module -- URI::Escape is only along for the ride.

Unfortunately, this minor version increment fails to communicate to downstream users that a potentially backwards-incompatible major version break has occurred.

The alternative: Per-distro dependency specification

Another approach is to assign a single $VERSION variable to the primary module in the distro, leaving all other modules without versions. This yields improvements in conceptual clarity.

Authors can still do evil things in the context of per-distro packaging, such as breaking back compat within a subcomponent without incrementing the distro's major version number. However, it is more obvious that you're doing something wrong because the distro's version number unambiguously represents everything together.

Removal of a subcomponent is likewise an unambiguous compatibility break -- that is, unless the subcompoment gets broken out into a new distro which gets added to the original distro's dependency chain as a mandatory prerequisite.

The downside is that we must assume that some fraction of the user base will attempt to specify per-module dependencies and will not get their desired behavior.

Recommendations Suggestions1

Fortunately, it is possible to emulate distro-level versioning while still supporting downstream users who make per-module dependency specifications:

  • Assign a $VERSION number in every provided package. (Admittedly, this is inconvenient and violates DRY; some projects use scripts to help ease the maintenance burden.)
  • Ensure that all $VERSION variables within a distro contain exactly the same value. (Some packaging tools provide validation routines.)
  • Treat the removal of a module from a distro as a backwards compatibility break.


This post is a spinoff from an off-topic thread on the cpan-testers-discuss list. The recommendations about $VERSION variables have been repeated many times elsewhere.

1 Update: "Suggestions" just sounds a little more humble the morning after. :)

In reply to Per-distro versioning and dependency specification by creamygoodness

Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":

  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?

    What's my password?
    Create A New User
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others taking refuge in the Monastery: (9)
    As of 2020-04-08 19:11 GMT
    Find Nodes?
      Voting Booth?
      The most amusing oxymoron is:

      Results (45 votes). Check out past polls.