I always keep the version numbers of modules in my distributions synchronised. While using different version numbers in different modules can be handled sanely, it seems to me there is at least potential for confusion. On the other hand, synchronisation doesn't appear to have many drawbacks. If I bump the version number of one module, then it doesn't seem harmful to bump the version numbers of the rest, even if they haven't seen any other changes.

With regard to changing major version numbers when breaking backwards compatibility, personally I don't think that goes far enough. If I write:

use Foo::Bar 2.00;
[download]

... but Foo::Bar 3.00 has a completely changed API, then my code may break in unexpected and confusing ways.

When JSON.pm changed its API between versions 1 and 2, this caused a lot of breakage. The only way to avoid that is to continue to support your old API alongside the new one. In practice this usually means giving your new API a different module name (and perhaps rewriting the old module as a wrapper for the new one).

It's tough to handle backwards compatibility breaks sanely in a dynamic environment. I agree that if you want to avoid disruption entirely in Perl 5, package renaming is the only option, and have in fact done something like what you recommend in the past.

Things would be easier if the language offered namespace aliasing a la Python and the community had a tradition of Java-like package namespaces.

use org::apache::spamassassin3::Mail::SpamAssassin as SpamAssassin;
my $spamtest = SpamAssassin->new();
[download]

Using the aliased module, you can almost get there in Perl 5, though aliased only aliases one package at a time rather than the whole hierarchy.

# Works:

use aliased 'org::apache::spamassassin3::Mail::SpamAssassin';
my $spamtest = SpamAssassin->new();

# Doesn't work:

use aliased org::apache::spamassassin3 => 'SA';
my $spamtest = SA::Mail::SpamAssassin->new();
[download]

Can you imagine the abuse that would rain down on someone who uploaded a tarball like org::apache::spamassassin3-3.31.tar.gz to CPAN, though?

Why is everybody copying version numbers all over the place in their distributions?

So, in the theoretical case of me writing a module that includes multiple packages where there isn't one "main" package that always gets used and so is the only place that needs to support "require at least version V", here is how I would implement that (because it means that there is exactly one place where I track the current version number):

Makefile.PL:
    ...
    VERSION_FROM => 'lib/My/Widget/Version.pm',
    ...

lib/My/Widget/Version.pm:
    package My::Widget::Version;
    require Exporter;
    our @EXPORT_OK = '$VERSION';
    *import = \&Exporter::import;
    our $VERSION = 1.011_021;

lib/My/Widget/Flanged.pm:
    package My::Widget::Flanged;
    use My::Widget::Version '$VERSION';
    ...
[download]

Nothing at all complicated about that. And if you don't want to pull in Exporter, then you have to have two simple lines in each "versioned" package instead of just the one.

Are there any ways in which that trivial solution is not better than any module that does work to copy-and-paste a version string into multiple files or that just checks that you did the copy-and-paste correctly?

I don't believe that the imported version numbers will be recognized by PAUSE. See the PAUSE documentation, and also this note in Perl::Critic::Policy::Modules::RequireVersionVar:

=head1 TO DO

Add check that C<$VERSION> is independently evaluatable.  In
particular, prohibit this:

    our $VERSION = $Other::Module::VERSION;

This doesn't work because PAUSE and other tools literally copy your
version declaration out of your module and evaluates it in isolation,
at which point there's nothing in C<Other::Module>, and so the
C<$VERSION> is undefined.
[download]

This may cause problems for downstream users who specify per-module dependencies. It's up to you whether you want to support them; some people feel quite strongly about it, such as "Anonymous Monk" above.

My first reaction was that I didn't think that I cared. PAUSE will get the correct version number for the distribution, which is what matters. 'require' will get the correct version number for what it does. I didn't think of any way that I would care what PAUSE thinks the version number is of a particular package.

Then I realized that the problem is probably that trying to set a dependency on " My::Widget::Flanged => 1.021_031" would be what could fail.

*sigh* Stupid tools are stupid. If there are indeed "install" tools that are stupid enough to fail for that case, then somebody should consider making them (or PAUSE or the latest "meta.today's-fad-data-encapsulation-format writer") smart enough to use the dist version for the module version when the module version appears to be beyond their ken. Of course, there surely are install tools that are that stupid. There's got to be a dozen install tools by now and most of the ones I've tried I quickly decided to never use again because of how stupid they were.

Not that I'm actually convinced that I care. One could still successfully declare a dependence on " My::Widget::Version => 1.021_031". Also, having such a distribution as I described probably means that My::Widget would be an even better place to put the version number and depending on " My::Widget => 1.021_041" is completely reasonable.

What I don't find reasonable is copying and pasting version numbers nor then building annoying tools to assist in that work and all just to allow people to use stupid tools stupidly.

Yeah, I'd rather document " My::Widget::Version => 1.021_041" being required than resort to copying and pasting version numbers.

Though, I find it quite a stretch to imagine myself writing a module distribution where any of this comes up. Given the stupidity of the tools that lead to this dilemma, I might even document that if you want to use My::Widget::Flanged and require at least version V of it, then you have to code that like:

use My::Widget::Version 1.021_031;
use My::Widget::Flanged;
[download]

- tye        

Congratulations on the stupidest least-well justified, most ill-thought-through recommendation I've seen in a very long time.

By reductio ad absurdum: Ubunto (substitute your favorite here) is a "distribution". It contains many "packages" -- over 1200 device drivers before you even start on the other components. If it incremented a single version 'number' every time any of those hundreds of subcomponents changed, it would seriously need to consider using 64-bit integers for each of the major(midor)minor components of the version 'number', lest it ran out of space.

Too big for this advise? How about GCC. If it incremented its version number every time one of it hundreds (thousands?) of subcomponents changed, its version numbers would read like a telephone numbers.

Still too big a project? At what point does this suggestion cease to be viable?

I would draw the line around any group of files which can only be installed together. That was what the phrase "atomic unit of installation" was intended to convey.

Ubuntu and GCC don't really fit into that context, as they are aggregations of smaller packages. Most CPAN tarballs would qualify, though, since perl Makefile.PL; make install is generally all or nothing.

Yeah, I disagree with pretty much everything you wrote

use/require work with modules, modules are the basis of reusable code in perl

Forcing the same $VERSION number in every provided package doesn't violate DRY but it also doesn't make sense as a standard or recommended practice

If you know, through consulting various Changes files, and through testing, that your code will only work if you  require CGI 2001; then go ahead and add use CGI 2001; otherwise don't specify a version number

You can use the output of Devel::Modlist and note in the documentation, that your module (or app, whatever) is known to work with this combination of modules/versions

Or you can turn this list into a list of author/distribution-name.tar.gz and create a Task which only installs this combination of dependencies.

Also, you don't say whom this recommendation is intended for :) but clearly anyone writing a lot of code (GAAS with his LWP.../URI... or say authors of Moose ) have already made up their mind and adopted a practice

The recommendations are for upstream authors.

FWIW, Moose's versioning is consistent with what the original post advocates (the version numbers for all modules in Moose-2.0602.tar.gz are synchronized at 2.0602). Downstream users are well-served regardless of whether their dependency specifications reference Moose itself or any number of its subcomponents.

there are numerous distributions (…) 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.

Perl::PrereqScanner makes short work of that.

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.

In the majority opinion, when someone does per-distro versioning, it constitutes an accidental bug and should be fixed to become per-module.

leaving all other modules without versions

There is no need for this proposal to be "universally accepted and implemented." :) I merely hope that individual authors will consider it.

As for exploding dependency lists using Perl::PrereqScanner, I'm agnostic. It might be good defensive programming for downstream users, but I think any upstream author who justifies recomposing a distribution on the basis of Perl::PrereqScanner's availability is irresponsible.

Ultimately, a version number has to stand for some bounded collection of code. My argument is that it assigning disparate version numbers to subdivisions within a collection of code which can only be installed as a single atomic unit is unhelpful, and thus that version numbers should be unified within such installation units.

For the sake of argument, why not assign version numbers to individual subroutines? Subroutines can be moved to different distros, too. Is Perl::PrereqScanner paranoid enough? :) Of course the answer is that the Perl 5 interpreter and use/require deal in modules with version numbers -- but there is tension between that and how modules typcially get packaged and installed as indivisible collections.

Now I might argue that it would be better logical behavior if the interpreter understood the concept of distros and dealt with version numbers at that level -- and that angle interests me as a student of language design and informs my opinions about best practice. However, in this Meditation I have attempted to limit the concrete suggestions to those which can implemented without either

• a time machine, or
• the unanimous consent of all CPAN authors.