> dzil

Managing Version Numbering with Dist::Zilla

Dist::Zilla needs to know the version of the distribution it's going to release so that it can build your META.json data and name the release tarball, but it can be useful for VCS integration, changelog management, and plenty of other things. The simplest way to specify your dist's version is to put it in dist.ini:

1:  2:

name = My-Dist version = 1.234

There are a number of plugins that put your version number to use. PkgVersion inserts a $VERSION definition in all your packages so that they'll all have versions matching distribution's version. NextRelease adds version headers to your changelog file so you don't need to worry about what the next version number will be until it's built. PodVersion or PodWeaver can insert a =head1 VERSION section in your documentation. The Git integration plugins system uses your version to tag releases.

All of these plugins go a long way to taking care of version accounting for you. PkgVersion and the Pod mungers, especially, eliminate the need to update multiple files in multiple ways.

The next step to letting Dist::Zilla help manage your versions is to let it manage your version numbering, too.

The AutoVersion Plugin

AutoVersion is a simple plugin that decides your version number automatically using a String::Formatter-powered sprintf-like format. The default format will generate a different version number for each day, so you don't need to worry about a thing if you're not doing multiple releases each day. You just add [AutoVersion] to your dist.ini and you'll get a version number like "0.101230"

If you do need an extra release, you can just set the environment variable N to up that last digit. This command would get you version "0.101235":

  $ N=5 dzil release

If you want change the leading number, you can supply a major parameter, and if you want a different format altogether, you can supply your own format string. For example, you could (but please don't!) get one-second resolution timestamp based versions with:

1:  2:

[AutoVersion] format = {{ cldr('yyyyMMdd') }}.{{ cldr('HHmmss') }}

Version Numbering from a Module

Traditional Makefile.PL- and Build.PL-based builds pick the distribution version number from the $VERSION assignment in the primary module in the distribution. In Dist::Zilla, that module is named by the main_module configuration parameter -- or more often, it's the module whose name matches your distribution name. If you want to get your distribution's version from your main module, you can just use VersionFromModule.

Version Numbering from Git

You could also avoid time-based versions by starting with your last version and incrementing it. Git::NextVersion does this. It starts by looking for version-like tags (using a regex configured by the version_regexp parameter), finds the greatest tagged version, and then sets the current build's version to the next version, calculated with Version::Next. When you release your dist, assuming you're using the Git::Tag plugin, your release will be automatically tagged and Git::NextVersion will do the right thing again on your next build.