Dist::Zilla::Plugin::MetaProvides::Update - A plugin to fix "provides" metadata after [RewriteVersion] modified $VERSION declarations
version 0.002
In your dist.ini (or a plugin bundle that effectively does the same thing):
[MetaProvides::*] ; e.g. ::Class, ::Package, ::FromFile ... [RewriteVersion] [MetaProvides::Update]
This plugin is a hack and hopefully will soon be made redundant. It is bundled along with a (the?) bundle that needs it, but can also be used with other bundles if such a need is identified.
This plugin is meant to be run after all other file mungers, but most particularly after [RewriteVersion]. Because plugin bundles contain many plugins, it can be difficult or impossible to arrange the order of plugins and bundles in dist.ini such that all ordering constraints are correctly satisfied.
The specific ordering problem that this plugin is correcting for is this:
a plugin runs in the FileMunging phase that requires metadata (in my case, I typically see this with [PodWeaver])
this prompts MetaProvider plugins to run, one of which populates "provides" metadata
all .pm files in the distribution are scanned and their $VERSION declarations are extracted
$VERSION
a subsequent FileMunging plugin adds or mutates these $VERSION declarations
now the "provides" metadata is incorrect.
Incorrect "provides" metadata is a big deal, because this metadata is treated as authoritative by PAUSE and can result in incorrect package indexing.
There are many $VERSION-mutating plugins, such as:
[PkgVersion]
[OurPkgVersion]
[RewriteVersion] (and its derivative, [RewriteVersion::Transitional])
Careful ordering of plugins can be used to avoid this issue: as long as the plugin that populates "provides" metadata appears in the configuration after the plugin that mutates $VERSION, everything works correctly. In my author bundle, I would prefer to list [RewriteVersion::Transitional] at the very beginning of the plugin list, to ensure module files are munged before any other plugins inspect them. However, correct ordering may no longer be possible if plugins are added from sub-bundles. I ran into this exact scenario when writing [@Git::VersionManager] -- all the plugins (except for [RewriteVersion::Transitional]) are after-release plugins, and need to run after other after-release plugins that the user may be using, so this likely results in the placement of the "provides" metadata-populating plugin as before these plugins.
My hacky (and hopefully temporary) solution is this plugin which runs after the $VERSION declaration is mutated, and hunts for the previous "provides" metadata-populating plugin and re-runs it, to update the metadata. Ideally, that plugin should do this itself as late as possible (such as in the Prereq Source phase), after all file munging is complete.
MetaProvides issue #8: warn when $VERSIONs are extracted from files too soon
[@Git::VersionManager]
Dist::Zilla::Role::MetaProvider::Provider
[MetaProvides::Package]
Bugs may be submitted through the RT bug tracker (or bug-Dist-Zilla-PluginBundle-Git-VersionManager@rt.cpan.org).
There is also a mailing list available for users of this distribution, at http://dzil.org/#mailing-list.
There is also an irc channel available for users of this distribution, at #distzilla on irc.perl.org.
#distzilla
irc.perl.org
I am also usually active on irc, as 'ether' at irc.perl.org.
Karen Etheridge <ether@cpan.org>
This software is copyright (c) 2017 by Karen Etheridge.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Dist::Zilla::PluginBundle::Git::VersionManager, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dist::Zilla::PluginBundle::Git::VersionManager
CPAN shell
perl -MCPAN -e shell install Dist::Zilla::PluginBundle::Git::VersionManager
For more information on module installation, please visit the detailed CPAN module installation guide.