Releasing trial/dev/beta versions with Dist::Zilla

You might have stumbled across Dist::Zilla's --trial command line option in the past, and maybe even used it for a developer CPAN release. Its effect is (as I understand it) two-fold:

  • adds -TRIAL to the name of the distribution archive being produced
  • sets release: testing in the META.json file which is parsed by CPAN services

It came to my attention that using -TRIAL is actually pretty bad for you and your system, and other users, even though it's one of the two naming conventions CPAN services use to identify developer releases.

The problem is that the actual $VERSION of your code is unaffected. This means once installed, you can't ask your computer the version of an installed distribution and work out from that whether it's a developer release, or not. A secondary issue is that in sites such as there's nothing really obvious about the release which highlights its status as "development", in the list of available versions.

An alternative way to signal to CPAN services that a dist is a trial release is to use an underscore and a secondary version number at the end of $VERSION, like _001. This is still a bit crappy but at least humans can really easily see what's going on.

Back to Dist::Zilla. If you use the AutoVersion plugin, a better alternative than using --trial is to set the DEV environment variable when you build or release the distribution. This has the effect of:

  • (sprintf '_%03u', $ENV{DEV}) being added to the end of $VERSION
  • sets release: testing in the META.json file which is parsed by CPAN services

Otherwise the best thing to do right now is to set the version manually, for developer releases. I hear from chatter on IRC that there are plans to change the --trial feature of Dist::Zilla to alter $VERSION if necessary (that is, if no underscore exists) - a good compromise, I reckon.


You misunderstand what “development” means with respect to a CPAN distribution. It means only that PAUSE won’t index the modules within the distribution.

You could have $VERSION=1.23 in your module but release it as “Dist-Name-1.23_01.tar.gz” and PAUSE won’t index it. Yet, once installed, you’ll only see the “1.23” that is in the module and will have no way of knowing that it came from a development release.

Underscores in $VERSION also have some problems, particular in “dotted-decimal” version numbers like “v1.2_3” depending on your version of Perl and/or (c.f. Version Numbers Should be Boring) Thankfully, many of those problems are going away as older Perls are phased out.

What the ‘-TRIAL’ suffix does is unambiguously signal to PAUSE that a distribution should not be indexed regardless of the version numbering scheme. It makes versioning and indexing orthogonal. Do you want semantic versioning with odd second terms to mean “development”? Now you can. You can also continue with the underscore convention if you want. The ‘-TRIAL’ suffix gives choices that didn’t exist before.

If isn’t showing that a distribution is a development release, then that’s just a bug and should be fixed.

Leave a comment

About Oliver Gorwits

user-pic Computer Networks is my business, so Perl is my glue.