Dist::Zilla::Plugin::BumpVersionAfterRelease - Bump module versions after distribution release
version 0.013
In your code, declare $VERSION like this:
$VERSION
package Foo; our $VERSION = '1.23';
In your dist.ini:
[RewriteVersion] [BumpVersionAfterRelease]
After a release, this module modifies your original source code to replace an existing our $VERSION = '1.23' declaration with the next number after the released version as determined by Version::Next.
our $VERSION = '1.23'
By default, versions must be "strict" -- decimal or 3+ part tuple with a leading "v". The allow_decimal_underscore option, if enabled, will also allow decimals to contain an underscore. All other version forms are not allowed, including: "v1.2", "1.2.3" and "v1.2.3_4".
allow_decimal_underscore
Only the first occurrence is affected (unless you set the "global" attribute) and it must exactly match this regular expression:
qr{^our \s+ \$VERSION \s* = \s* '$version::LAX'}mx
It must be at the start of a line and any trailing comments are deleted. The original may have double-quotes, but the re-written line will have single quotes.
The very restrictive regular expression format is intentional to avoid the various ways finding a version assignment could go wrong and to avoid using PPI, which has similar complexity issues.
For most modules, this should work just fine.
This Dist::Zilla plugin, along with RewriteVersion let you leave a $VERSION declaration in the code files in your repository but still let Dist::Zilla provide automated version management.
First, you include a very specific $VERSION declaration in your code:
our $VERSION = '0.001';
It must be on a line by itself and should be the same in all your files. (If it is not, it will be overwritten anyway.)
RewriteVersion is a version provider plugin, so the version line from your main module will be used as the version for your release.
If you override the version with the V environment variable, then RewriteVersion will overwrite the $VERSION declaration in the gathered files.
V
V=1.000 dzil release
Finally, after a successful release, this module BumpVersionAfterRelease will overwrite the $VERSION declaration in your source files to be the next version after the one you just released. That version will then be the default one that will be used for the next release.
You can configure which files have their $VERSION declarations modified, with the finder option. The default finders are :InstallModules and :ExecFiles; other predefined finders are listed in "default_finders" in Dist::Zilla::Role::FileFinderUser.
finder
:InstallModules
:ExecFiles
If you tag/commit after a release, you may want to tag and commit before the source files are modified. Here is a sample dist.ini that shows how you might do that.
dist.ini
name = Foo-Bar author = David Golden <dagolden@cpan.org> license = Apache_2_0 copyright_holder = David Golden copyright_year = 2014 [@Basic] [RewriteVersion] ; commit source files as of "dzil release" with any ; allowable modifications (e.g Changes) [Git::Commit / Commit_Dirty_Files] ; commit files/Changes (as released) ; tag as of "dzil release" [Git::Tag] ; update Changes with timestamp of release [NextRelease] [BumpVersionAfterRelease] ; commit source files after modification [Git::Commit / Commit_Changes] ; commit Changes (for new dev) allow_dirty_match = ^lib/ commit_msg = Commit Changes and bump $VERSION
By default, versions must meet the 'strict' criteria from version, which does not allow the use of underscores.
If the allow_decimal_underscore options is set to true, you may use underscores in decimal versions. In this case, the following line will be added after the $VERSION assignment to ensure the underscore is removed at runtime:
$VERSION = eval $VERSION;
Despite their long history on CPAN, the author does not recommend the use of decimal underscore versions with Dist::Zilla, as Dist::Zilla supports generating tarballs with a "-TRIAL" part of the name as well as putting a release_status in META.json – both of which prevent PAUSE from indexing a distribution.
release_status
Plus, since this plugin also adds the '# TRIAL' comment on the version line, it's obvious in the source that the module is a development release. With both source and tarball obviously marked "TRIAL", most of the historical need for underscore in a version is taken care of.
Using decimal underscores (with the "eval" hack ) introduces a subtle difference between what the MM->parse_version thinks the version is (and what is in META) and what Perl thinks the version is at runtime.
MM->parse_version
Foo->VERSION eq MM->parse_version( $INC{"Foo.pm"} )
This would be false for the version "1.002_003" with $VERSION = eval $VERSION. Much of the toolchain has heuristics to deal with this, but it may be an issue depending on exactly what version of toolchain modules you have installed. You can avoid all of it by just not using underscores.
$VERSION = eval $VERSION
On the other hand, using underscores and not using eval $VERSION leads to even worse problems trying to specify a version number with use:
eval $VERSION
use
# given $Foo::VERSION = "1.002_003" use Foo 1.002_003; # fails!
Underscore versions were a useful hack, but now it's time to move on and leave them behind. But, if you really insist on underscores, the allow_decimal_underscore option will let you.
Yes, Perl allows this: v1.2.3_4. And even this: 1.2.3_4. And this: v1.2_3. Or any of those in quotes. (Maybe)
v1.2.3_4
1.2.3_4
v1.2_3
But what happens is a random function of your version of Perl, your version of version.pm, and your version of the CPAN toolchain.
So you really shouldn't use underscores in version tuples, and this module won't let you.
Allows use of decimal versions with underscores. Default is false. (Version tuples with underscores are never allowed!)
If true, all occurrences of the version pattern will be replaced. Otherwise, only the first occurrence is replaced. Defaults to false.
If there is a Makefile.PL in the root of the repository, its version will be set as well. Defaults to true.
Here are some other plugins for managing $VERSION in your distribution:
Dist::Zilla::Plugin::PkgVersion
Dist::Zilla::Plugin::OurPkgVersion
Dist::Zilla::Plugin::OverridePkgVersion
Dist::Zilla::Plugin::SurgicalPkgVersion
Dist::Zilla::Plugin::PkgVersionIfModuleWithPod
Dist::Zilla::Plugin::RewriteVersion::Transitional
Please report any bugs or feature requests through the issue tracker at https://github.com/dagolden/Dist-Zilla-Plugin-BumpVersionAfterRelease/issues. You will be notified automatically of any progress on your issue.
This is open source software. The code repository is available for public review and contribution under the terms of the license.
https://github.com/dagolden/Dist-Zilla-Plugin-BumpVersionAfterRelease
git clone https://github.com/dagolden/Dist-Zilla-Plugin-BumpVersionAfterRelease.git
David Golden <dagolden@cpan.org>
David Golden <xdg@xdg.me>
Karen Etheridge <ether@cpan.org>
Kent Fredric <kentfredric@gmail.com>
Klaus Eichner <klaus03@gmail.com>
This software is Copyright (c) 2014 by David Golden.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
To install Dist::Zilla::Plugin::BumpVersionAfterRelease, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dist::Zilla::Plugin::BumpVersionAfterRelease
CPAN shell
perl -MCPAN -e shell install Dist::Zilla::Plugin::BumpVersionAfterRelease
For more information on module installation, please visit the detailed CPAN module installation guide.