Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl: the Markov chain saw

Re: Sane deprecation policy for a CPAN module? (Software Versioning)

by eyepopslikeamosquito (Bishop)
on Nov 18, 2018 at 20:43 UTC ( #1225988=note: print w/replies, xml ) Need Help??

in reply to Sane deprecation policy for a CPAN module?

Thanks for asking this -- it reminded me I need to update Writing Solid CPAN Modules with advice on CPAN Module Versioning.

Short Summary

For a new module, start by adding the line:

our $VERSION = '0.01';
near the top of the file (shortly after the module's package statement). Note that our was introduced in Perl 5.6.0. If you need to support Perl versions earlier than that, use instead:
use vars qw($VERSION); $VERSION = '0.01';
With that done, simply bump up the value of $VERSION as you add new features; for example '0.01', '0.02', '0.03' and so on.

When you have finally produced a stable, production quality API, on which users have come to depend, it is a good idea to indicate that by bumping the module version to '1.00' or higher. And further to set your CPAN distribution's CPAN::Meta::Spec's release_status to "stable" (other values for this piece of CPAN distribution metadata are "testing" and "unstable").

General Software Versioning Refs

  • SemVer (Semantic Versioning in Software Management)
  • This node mentions "C++ as a Live at Head Language" talk by Titus Winters, which describes Google's real world experiences with library versioning in huge code bases and why SemVer proved inadequate for them.
  • API Change Strategy
  • Stack Exchange question

CPAN Versioning Refs

  • perlmodlib : see "Guidelines for Module Creation" section. From that section: "To be fully compatible with the Exporter and MakeMaker modules you should store your module's version number in a non-my package variable called $VERSION. This should be a positive floating point number with at least two digits after the decimal (i.e., hundredths, e.g, $VERSION = "0.01"). Don't use a "1.3.2" style version. See (Module Version Checking) in Exporter for details". From the "Version numbering" sub-section: "The most common CPAN version numbering scheme looks like this: 1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32".
  • CPAN::Meta::Spec by xdg - specification for CPAN distribution metadata, see especially release_status field (with values 'stable', 'testing', 'unstable').

Other Refs

Note: apparently Perl Best Practices got this wrong (in Modules chapter, 221. Use three-part version numbers; 222. Enforce your version requirements programmatically) and so is a dubious reference on CPAN module versioning.

Some Perl Monks Versioning Nodes

META.yml and META.json

Deprecating a CPAN module

  • XML::XSH by choroba - There is a big warning right at the top "This module is deprecated, use XML::XSH2 instead".
  • XML::XSH2 by choroba - This is the current one. Looking forward to XSH3, XSH4, XSH5, ... :)
  • Hmmm, CPAN::Meta::Spec does not appear to have a Deprecated status, release_status has only "stable", "testing", "unstable".

Judging the Quality of a CPAN module

TODO: Finish this section and point to it from "Dependencies" section of Writing Solid CPAN Modules

Warning signs:

  • Bad reviews
  • Only one release and/or hasn't had releases for many years
  • Its test statistics show a lot of failures
  • Lots of unresolved bugs
  • CPANTS Kwalitee score (e.g. A::E kwalitee)

Discouraged modules:

  • Switch
  • File::Slurp (has a lot of issues, better to slurp manually)
  • XML::Simple (only useful for a very narrow range of tasks, better modules like XML::Twig, XML::Rules, or XML::LibXML)
  • CGI (consider more modern web frameworks, such as Catalyst, Dancer/Dancer2, and Mojolicious)

Note: Many updates were made long after the original reply - in preparation for later insertion into Writing Solid CPAN Modules

Replies are listed 'Best First'.
Re^2: Sane deprecation policy for a CPAN module?
by Dallaylaen (Chaplain) on Nov 19, 2018 at 04:42 UTC
    Well at least I got my version numbers right, apart from skipping x.y0 which I'm going to take up now.

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://1225988]
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others imbibing at the Monastery: (7)
As of 2021-06-22 07:01 GMT
Find Nodes?
    Voting Booth?
    What does the "s" stand for in "perls"? (Whence perls)

    Results (101 votes). Check out past polls.