WHAT?

Version::Dotted and its subclasses complement standard version class with
version modification operations, which can be useful in distribution release
tools.

WHY?

In my AfterRelease Dist::Zilla plugin I need to bump current distribution
version.

I version is an official Perl module (and also a module recommended by
Task::Kensho) to compare versions:

    if ( version->parse( $Module::VERSION ) < '0.10.1' ) {
        plan skip_all => "Module $Module::VERSION too old";
    };

When I had a need to manipulate versions, I started to use Perl::Version
(another module recommended by Task::Kensho) because version does not provide
any method to modify version object. I wanted to bump version of a distribution
automatically after release, and Perl::Version did the job for me:

    my $v = Perl::Version->new( $self->zilla->version );
    $v->inc_alpha();

(The idea is: If I just released v0.10.1, the version of the next release would
be automatically set to v0.10.1_01. If I released v0.10.1_01, the next version
would be v0.10.1_02, and so on. If I decided it is time to release non-trial
version, I would manually set version to v0.10.2 or whatever else, e. g. v0.11.0
or v1.0.0.)

Everything was ok. However, I accidentally found that

    version->parse( 'v0.10.1_01' ) > 'v0.10.2'  # is true

Oops. That's was quite surprising, because some time ago this expression had
opposite result:

    version->parse( 'v0.10.1_01' ) < 'v0.10.2'  # was true

Little investigation shown the breaking change is in version 0.9913: earlier
versions interpret underscore as version part delimiter ('v0.10.1_01' is the
same as 'v0.10.1.1'+trial), but 0.9913 and later versions do not ('v0.10.1_01'
is the same as 'v.10.101'+trial).

Ignoring underscore is probably a right thing to do, because it is the way how
Perl itself interprets v-strings:

    v0.10.1_01 eq v0.10.101     # is true

but it is definitely a change which makes Perl::Version useless (to me).

NAMING

perl-Version-Dotted is official software name.

However, in Perl world prefix "perl-" is redundant and not used. For example, on
meta::cpan <https://metacpan.org/> this software is named as Version-Dotted. In
the rest of the documentation shortened name Version-Dotted is used as synonym
for full name perl-Version-Dotted. We are in the Perl world, aren't we?

You may notice that name may be spelled with dashes (Version-Dotted) or with
double colons (Version::Dotted). Strictly speaking, there is difference: the
first one is software name, while the second is name of Perl package, but often
these names are interchangeable especially if software consists of single
package.

FORMS

You may face Version-Dotted in *source* or *distribution* forms.

If you are going to tODO, you will likely be interested in *using*
Version-Dotted *distribution*. If you are going to *develop* (or *hack*) the
Version-Dotted itself, you will likely need the *source*, not distribution.

Since Perl is an interpreting language, modules in the distribution *look* like
sources. Actually, they are Perl source files. But they are not *actual*
sources, because they are *built* (preprocessed or generated) by Dist-Zilla.

How to distinguish source and distribution:

*   Source may contain Mercurial files and directories .hgignore, .hgtags, .hg/,
    while distribution should not.

*   Source should contain dist.ini file, while distribution may not.

*   Source should *not* contain xt/ directory, while distribution should.

*   Name of source directory does *not* include version (e. g. Version-Dotted),
    while name of distribution does (e. g. Version-Dotted-v0.7.1).

SOURCE

Version-Dotted source is in Mercurial repository hosted on fedorapeople.org. To
clone the entire repository:

    $ hg clone https://vandebugger.fedorapeople.org/hg/perl-Version-Dotted

Source Files

Version-Dotted source files usually include a comment near the top of the file:

    This file is part of perl-Version-Dotted.

Not all source files are included into distribution. Some source files are used
at distribution build time only, and not required for installation.

DISTRIBUTION

Version-Dotted distributions are published on CPAN
<https://metacpan.org/release/Version-Dotted>.

Generated Files

Distribution may contain files preprocessed or generated by Dist-Zilla and its
plugins. Some generated files are made from Version-Dotted source, but some are
generated from third-party templates. Files generated from third-party templates
usually include a comment near the top of the file:

    This file was generated with NAME

(where *NAME* is a name of the plugin generated the file). Such files are *not*
part of Version-Dotted source, and Version-Dotted copyright and license are not
applicable to such files.

INSTALLING

With cpanm

cpanm tool is (probably) the easiest way to install distribution. It automates
downloading, building, testing, installing, and uninstalling.

To install the latest version from CPAN:

    $ cpanm Version::Dotted

To install a specific version (e. g. *v0.7.1*) from CPAN:

    $ cpanm Version::Dotted@v0.7.1

To install locally available distribution (e. g. previously downloaded from CPAN
or built from sources):

    $ cpanm ./Version-Dotted-v0.7.1.tar.gz

To uninstall the distribution:

    $ cpanm -U Version::Dotted

Manually

To install distribution tarball manually (let us assume you have version
*v0.7.1* of the distribution):

    $ tar xaf Version-Dotted-v0.7.1.tar.gz
    $ cd Version-Dotted-v0.7.1
    $ perl Build.PL
    $ ./Build build
    $ ./Build test
    $ ./Build install

See Also

How to install CPAN modules <http://www.cpan.org/modules/INSTALL.html>

HACKING

For hacking, you will need Mercurial, Perl interpreter and Dist-Zilla (with some
plugins), and likely cpanm to install missed parts.

Clone the repository first:

    $ hg clone https://vandebugger.fedorapeople.org/hg/perl-Version-Dotted
    $ cd perl-Version-Dotted

To build a distribution from the source, run:

    $ dzil build

If required Dist-Zilla plugins are missed, the dzil tool will warn you and show
the command to install all the required plugins, e. g.:

    Required plugin Dist::Zilla::Plugin::Test::EOL isn't installed.

    Run 'dzil authordeps' to see a list of all required plugins.
    You can pipe the list to your CPAN client to install or update them:

        dzil authordeps --missing | cpanm

To run the tests (to check primary software functionality):

    $ dzil test

To run extended tests (to check source code style, documentation and other
things which are not too important for software end users):

    $ dzil xtest

To install the distribution:

    $ dzil install

or

    $ cpanm ./Version-Dotted-VERSION.tar.gz

where *VERSION* is a version of built distribution.

To clean the directory:

    $ dzil clean

DOCUMENTATION

Online

The easiest way is browsing the documentation online at meta::cpan
<https://metacpan.org/release/Version-Dotted>.

Locally Installed

If you have the distribution installed, use perldoc tool to browse locally
installed documentation:

    $ perldoc Version::Dotted::Manual
    $ perldoc Version::Dotted

Built from Source

Build Version-Dotted first (see "HACKING"), then:

    $ cd Version-Dotted-VERSION
    $ perldoc Version::Dotted::Manual
    $ perldoc Version::Dotted

where *VERSION* is a version of built distribution.

FEEDBACK

CPAN Request Tracker

The quickest way to report a bug in Version-Dotted is by sending email to
bug-Version-Dotted [at] rt.cpan.org.

CPAN request tracker can be used via web interface also:

Browse bugs <https://rt.cpan.org/Public/Dist/Display.html?Name=Version-Dotted>
    Browsing bugs does not require authentication.

Report bugs <https://rt.cpan.org/Public/Bug/Report.html?Queue=Version-Dotted>
    You need to be a CPAN author, have a BitCard <https://www.bitcard.org/>
    account, or OpenID in order to report bugs via the web interface.

    (On 2015-04-27 I have logged in successfully with my LiveJournal OpenID, but
    my Google OpenID did not work for CPAN. I did not check other OpenID
    providers.)

Send Email to Author

As a last resort, send email to author: Van de Bugger <van.de.bugger@gmail.com>.
Please start message subject with "perl-Version-Dotted:".

GLOSSARY

CPAN
    Comprehensive Perl Archive Network, a large collection of Perl software and
    documentation. See cpan.org <http://www.cpan.org>, What is CPAN?
    <http://www.cpan.org/misc/cpan-faq.html#What_is_CPAN>.

Distribution
    Tarball, containing Perl modules and accompanying files (documentation,
    metainfo, tests). Usually distributions are uploaded to CPAN, and can be
    installed with dedicated tools (cpan, cpanm, and others).

Module
    Perl library file, usually with .pm suffix. Usually contains one package.
    See perlmod <http://perldoc.perl.org/perlmod.html#Perl-Modules>.

Package
    Perl language construct. See package
    <http://perldoc.perl.org/functions/package.html> and perlmod
    <http://perldoc.perl.org/perlmod.html#Packages>.
