NAME

Dist::Zilla::Plugin::MetaProvides::Update - A plugin to fix "provides" metadata after [RewriteVersion] modified $VERSION declarations

VERSION

version 0.004

SYNOPSIS

In your dist.ini (or a plugin bundle that effectively does the same thing):

    [MetaProvides::*]   ; e.g. ::Class, ::Package, ::FromFile
    ...
    [RewriteVersion]
    [MetaProvides::Update]

DESCRIPTION

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

• 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.

SEE ALSO

• MetaProvides issue #8: warn when $VERSIONs are extracted from files too soon

• [@Git::VersionManager]

• Dist::Zilla::Role::MetaProvider::Provider

• [MetaProvides::Package]

SUPPORT

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.

I am also usually active on irc, as 'ether' at irc.perl.org.

AUTHOR

Karen Etheridge <ether@cpan.org>

COPYRIGHT AND LICENCE

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.