The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
NAME
    Dist::Zilla::Plugin::BumpVersionAfterRelease - Bump module versions
    after distribution release

VERSION
    version 0.016

SYNOPSIS
    In your code, declare $VERSION like this:

        package Foo;
        our $VERSION = '1.23';

    In your dist.ini:

        [RewriteVersion]

        [BumpVersionAfterRelease]

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

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

    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.

USAGE
    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=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.

    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.

        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

  Using underscore in decimal $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.

    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.

        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.

    On the other hand, using underscores and not using "eval $VERSION" leads
    to even worse problems trying to specify a version number with "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.

  Using underscore in tuple $VERSION
    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)

    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.

ATTRIBUTES
  allow_decimal_underscore
    Allows use of decimal versions with underscores. Default is false.
    (Version tuples with underscores are never allowed!)

  global
    If true, all occurrences of the version pattern will be replaced.
    Otherwise, only the first occurrence in each file is replaced. Defaults
    to false.

  all_matching
    If true, only versions matching that of the last release will be
    replaced. Defaults to false.

  munge_makefile_pl
    If there is a Makefile.PL in the root of the repository, its version
    will be set as well. Defaults to true.

  munge_build_pl
    If there is a Build.PL in the root of the repository, its version will
    be set as well. Defaults to true.

SEE ALSO
    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

SUPPORT
  Bugs / Feature Requests
    Please report any bugs or feature requests through the issue tracker at
    <https://github.com/dagolden/Dist-Zilla-Plugin-BumpVersionAfterRelease/i
    ssues>. You will be notified automatically of any progress on your
    issue.

  Source Code
    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

AUTHOR
    David Golden <dagolden@cpan.org>

CONTRIBUTORS
    *   Dave Rolsky <autarch@urth.org>

    *   David Golden <xdg@xdg.me>

    *   Karen Etheridge <ether@cpan.org>

    *   Kent Fredric <kentfredric@gmail.com>

    *   Klaus Eichner <klaus03@gmail.com>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2014 by David Golden.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004