/ 
Dist-Zilla-PluginBundle-Git-VersionManager-0.007
River stage one • 4 direct dependents • 5 total dependents
/ Dist::Zilla::PluginBundle::Git::VersionManager

NAME

Dist::Zilla::PluginBundle::Git::VersionManager - A plugin bundle that manages your version in git

VERSION

version 0.007

SYNOPSIS

In your dist.ini:

[@Author::You], or other config entries...

[@Git::VersionManager]
[Git::Push]

Or, in your plugin bundle's configure method:

$self->add_plugin(...);
$self->add_bundle('@Git::VersionManager' => \%options)
$self->add_plugin('Git::Push');

DESCRIPTION

This is a Dist::Zilla plugin bundle that manages the version of your distribution, and the $VERSION of the modules within it. The current version (of the release in question) is determined from our $VERSION = ... declarations in the code (or from the V environment variable), the Changes file is updated and committed as a release commit to git, which is then tagged, and then the $VERSION in code is then incremented and then that change is committed. The default options used for the plugins are carefully curated to work together, but all can be customized or overridden (see below).

Modules without $VERSION declarations will have them added for the release, with that change also committed back to the local repository.

When no custom options are passed, it is equivalent to the following configuration directly in a dist.ini:

[Prereqs / pluginbundle version]
-phase = develop
-relationship = recommends
Dist::Zilla::PluginBundle::Git::NextVersion = <current installed version>

[RewriteVersion::Transitional]
:version = 0.004

; ... and whatever plugin and configs were specified in <fallback_version_provider>

[MetaProvides::Update]

[CopyFilesFromRelease / copy Changes]
filename = Changes

[Git::Commit / release snapshot]
:version = 2.020
allow_dirty = Changes
allow_dirty = ... anything else passed in 'commit_files_after_release'

[Git::Tag]

[BumpVersionAfterRelease::Transitional]
:version = 0.004

[NextRelease]
:version = 5.033
time_zone = UTC
format = %-8v  %{yyyy-MM-dd HH:mm:ss'Z'}d%{ (TRIAL RELEASE)}T

[Git::Commit / post-release commit]
:version = 2.020
allow_dirty = Changes
allow_dirty_match = ^lib/.*\.pm$
commit_msg = increment $VERSION after %v release

[Prereqs / prereqs for @Git::VersionManager]
-phase = .. if plugin_prereq_phase specified ..
-relationship = .. if plugin_prereq_relationship specified ..
...all the plugins this bundle uses...

OPTIONS / OVERRIDES

bump_only_matching_versions

If your distribution has many module files, and not all of them have a $VERSION declaration that matches the main module (and distribution) version, set this option to true. This has two effects that differ from the default case:

  • while preparing the build and release, no module $VERSION declarations will be altered to match the distribution version (therefore they must be set to the desired values in advance).

  • after the release, only module $VERSION declarations that match the release version will see their values incremented. All $VERSIONs that do not match will be left alone: you must manage them manually. Likewise, no missing $VERSIONs will be added.

Defaults to false (meaning all modules will have their $VERSION declarations synchronized before release and incremented after release).

First available in version 0.003.

commit_files_after_release

File(s), which are expected to exist in the repository directory, to be committed to git as part of the release commit. Can be used more than once. When specified, the default is appended to, rather than overwritten. Defaults to Changes.

Note that you are responsible for ensuring these files are in the repository (perhaps by using [CopyFilesFromRelease]. Additionally, the file(s) will not be committed if they do not already have git history; for new files, you should add the add_files_in = . configuration (and use [Git::Check] to ensure that only these files exist in the repository, not any other files that should not be added.)

changes_version_columns

An integer that specifies how many columns (right-padded with whitespace) are allocated in Changes entries to the version string. Defaults to 10. Unused if NextRelease.format = anything is passed into the configuration.

plugin_prereq_phase, plugin_prereq_relationship

If these are set, then plugins used by the bundle (with minimum version requirements) are injected into the distribution's prerequisites at the specified phase and relationship. By default these options are disabled. If set, the recommended values are develop and suggests.

First available in version 0.004.

other customizations

This bundle makes use of Dist::Zilla::Role::PluginBundle::PluginRemover and Dist::Zilla::Role::PluginBundle::Config::Slicer to allow further customization. (Note that even though some overridden values are inspected in this class, they are still overlaid on top of whatever this bundle eventually decides to pass -- so what is in the dist.ini or in the add_bundle arguments always trumps everything else.)

Plugins are not loaded until they are actually needed, so it is possible to --force-install this plugin bundle and -remove some plugins that do not install or are otherwise problematic (although release functionality will likely be broken, you should still be able to build the distribution, more or less).

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.