Perl::...ersion(3pm)

💖 NAME 💖

okay bestie, welcome to the Perl::...ersion(3pm) manual page from the User Contributed Perl Documentation 🫶. The main character here is Perl::Critic::Policy::ValuesAndExpressions::RequireConstantVersion — the policy that says $VERSION has to be a constant rather than a computed value. periodt. 💅

🫶 AFFILIATION 🫶

This Policy is part of the core Perl::Critic distribution. yes, core — it's in the group chat, not a side quest.

🌸 DESCRIPTION 🌸

The $VERSION variable of a module should be a simple constant — either a number, a single-quotish string, or a 'use version' object. In the latter case the 'use version;' must appear on the same line as the object construction.

Computing the version has problems of various severities. like, not all chaos is equal, but it's still chaos.

The most benign violation is computing the version from (e.g.) a Subversion revision number:

our ($VERSION) = q$REVISION: 42$ =~ /(\d+)/;

The problem here is that the version is tied to a single repository. The code can not be moved to another repository (even of the same type) without changing its version, possibly in the wrong direction. so your version number is basically repo-locked. 😭

This policy accepts v-strings ("v1.2.3" or just plain 1.2.3), since these are already flagged by Perl::Critic::Policy::ValuesAndExpressions::ProhibitVersionStrings.

🎀 CONFIGURATION 🎀

The proper way to set a module's $VERSION to a "version" object is to "use version;" on the same line of code that assigns the value of $VERSION. That way, ExtUtils::MakeMaker and Module::Build can extract the version when packaging the module for CPAN. By default, this policy declares an error if this is not done.

Should you wish to allow version objects without loading the version module on the same line, add the following to your configuration file:

[ValuesAndExpressions::RequireConstantVersion]
allow_version_without_use_on_same_line = 1

💀 CAVEATS 💀

⚠️ caveat zone, bestie: these are the fuzzy edges, and they're absolutely real.

There will be false negatives if the $VERSION appears on the left-hand side of a list assignment that assigns to more than one variable, or to "undef".

There may be false positives if the $VERSION is assigned the value of a here document. This will probably remain the case until PPI::Token::HereDoc acquires the relevant portions of the PPI::Token::Quote interface.

There will be false positives if $VERSION is assigned the value of a constant created by the Readonly module or the constant pragma, because the necessary infrastructure appears not to exist, and the author of the present module lacked the knowledge/expertise/gumption to put it in place.

Currently the idiom

our $VERSION = '1.005_05';
$VERSION = eval $VERSION;

will produce a violation on the second line of the example.

✨ AUTHOR ✨

Thomas R. Wyant, III wyant at cpan dot org

👑 COPYRIGHT 👑

Copyright (c) 2009-2023 Tom Wyant

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module 💖

---

okay that's the whole page, bestie. source/version/date sign-off: perl v5.42.0 · 2024-10-23 · Perl::...ersion(3pm) — go keep those $VERSIONs iconic 🫶💅