# lib/Software/License/OrLaterPack.pod #

=pod

=encoding UTF-8

=head1 WHAT?

C<Software-License-OrLaterPack> is an add-on for C<Software-License>, a set of licenses with "or
later" clause (like C<GPL_3::or_later> and C<AGPL_3::or_later>). It allows Perl developers (who use
C<Dist-Zilla>) to release their work under the terms of a I<License> version I<N> or (at user
option) any later version.

C<Software-License-OrLaterPack> is free sotfware.

=cut
=pod

=encoding UTF-8

=head1 QUICK START

Install the distribution:

    $ cpanm Software::License::OrLaterPack

Then use desired license in your F<dist.ini> file, e. g.:

    license = GPL_3::or_later

=cut
=pod

=encoding UTF-8

=head1 LIST OF PROVIDED LICENSES

=over

=item C<AGPL_3::or_later>

=item C<GPL_3::or_later>

=back

=cut
=pod

=encoding UTF-8

=head1 WHY?

C<Dist-Zilla> is a popular tool for building CPAN distributions. Build process is controlled by
F<dist.ini>, C<Dist-Zilla> configuration file. A distribution author can specify license covering
his work by a line in F<dist.ini> file:

    license = NAME

where I<NAME> is a name of module from L<Software::License> hierarchy.

C<Software-License> is shipped with a set of popular licenses, from C<Apache_1_1> to C<Zlib>,
including GNU General Public licenses (GPL) C<GPL_1>, C<GPL_2>, C<GPL_3>, including their "Lesser"
and "Affero" variants (C<LGPL_2_1> and <AGPL_3>, to name a few).

So, if a developer wants to release his work under GPLv3 license terms, he should write in his
F<dist.ini>:

    license = GPL_3

However, L<Free Software Foundation recommends using clause "license version I<N> or (at your
option) any later version"|https://www.gnu.org/licenses/gpl-faq.html#VersionThreeOrLater>.
Unfortunately, C<Software-License> distribution does not supply (out of the box) a way to express
such clause.

C<Software-License-OrLaterPack> fulfills the lack, at least partially.

=cut
=pod

=encoding UTF-8

=head1 SOURCE vs DISTRIBUTION

You may face C<Software-License-OrLaterPack> in I<source> or I<distribution> form.

If you are going to release I<your> Perl distribution under the terms of GPLv3+ or AGPLv3+ license,
you will likely be interested in I<using> C<Software-License-OrLaterPack> I<distribution>.

Since Perl is an interpreting language, modules in the distribution I<look> like sources. Actually,
they are Perl source files. But they are not I<actual> sources, because they are I<built>
(preprocessed or generated) by L<Dist::Zilla>. If you are going to I<develop> (or I<hack>) the
C<Software-License-OrLaterPack> itself, you will likely need the I<actual source>, not
distribution.

How to distinguish source and distribution:

=over

=item *

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

=item *

Source should contain files F<dist.ini>, F<weaver.ini>, while distribution may not.

=item *

Source should I<not> contain F<xt/> directory, while distribution should.

=item *

Name of source directory does I<not> include version, while name of distribution does.

=back

=cut
=pod

=encoding UTF-8

=head1 SOURCE

C<Software-License-OrLaterPack> source is in L<Mercurial repository hosted on
SourceForge|http://hg.code.sf.net/p/orlaterpack/code/>.

C<Software-License-OrLaterPack> source files usually include a comment near the top of the file:

    This file is part of Software-License-OrLaterPack.

Source may include files which are useful for hacking but not needed for installing. Such files are
not included into distribution.

=cut
=pod

=encoding UTF-8

=head1 DISTRIBUTION

C<Software-License-OrLaterPack> distributions are published on
L<CPAN|https://metacpan.org/release/Software-License-OrLaterPack>.

=head2 Generated files

Distribution may cointain files preprocessed or generated by C<Dist-Zilla> and its plugins. Some
generated files are made from C<Software-License-OrLaterPack> 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 XXX

(where I<XXX> is a name of the plugin generated the file). Such files are I<not> part of
C<Software-License-OrLaterPack> source.

=cut
=pod

=encoding UTF-8

=head1 INSTALLING A DISTRIBUTION

=head2 With cpanm

C<cpanm> tool is the easiest way to install distribution. It automates downloading, building,
testing, installing, and uninstalling.

To install the latest version from CPAN:

    $ cpanm Software::License::OrLaterPack

To install a specific version (e. g. I<0.007>) from CPAN:

    $ cpanm Software::License::OrLaterPack@0.007

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

    $ cpanm ./Software-License-OrLaterPack-0.007.tar.gz

To uninstall the distribution:

    $ cpanm -U Software::License::OrLaterPack

=head2 Manually

To install distribution tarball manually (let us assume you have version I<0.007> of the
distribution):

    $ tar xaf Software-License-OrLaterPack-0.007.tar.gz
    $ cd Software-License-OrLaterPack-0.007
    $ perl Build.PL
    $ ./Build build
    $ ./Build test
    $ ./Build install

=cut
=pod

=encoding UTF-8

=head1 HACKING THE SOURCE

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

Clone the repository first:

    $ hg clone http://hg.code.sf.net/p/orlaterpack/code/ \
    Software-License-OrLaterPack
    $ cd Software-License-OrLaterPack

To build a distribution from source, run:

    $ PERL5LIB=lib:$PERL5LIB dzil build

If required C<Dist-Zilla> plugins are missed, C<dzil> tool will warn you and show the command to
install all the required plugins.

To run the tests:

    $ PERL5LIB=lib:$PERL5LIB dzil test

To run all the tests, including release tests:

    $ PERL5LIB=lib:$PERL5LIB dzil test --release

To install the distribution:

    $ PERL5LIB=lib:$PERL5LIB dzil install

or

    $ cpanm ./Software-License-OrLaterPack-VERSION.tar.gz

where I<VERSION> is a version of built distribution.

=cut
=pod

=encoding UTF-8

=head1 BROWSING THE DOCUMENTATION

=head2 Online

The easiest way is browsing the documentation L<online at
CPAN|https://metacpan.org/pod/Software::License::OrLaterPack>.

=head2 Locally installed

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

    $ perldoc Software::License::OrLaterPack
    $ perldoc Software::License::GPL_3::or_later

=head2 Built from source

If you are hacking the sources, build C<Software-License-OrLaterPack> first,
then:

    $ PERL5LIB=lib:$PERL5LIB perldoc Software::License::OrLaterPack
    $ PERL5LIB=lib:$PERL5LIB perldoc Software::License::GPL_3::or_later

=cut
=pod

=encoding UTF-8

=head1 REPORTING BUGS

There are few ways to reports bugs and/or provide feedback:

=head2 Bug tracker at CPAN

You need an CPAN/PAUSE account in oder to report bugs via the web interface. Alternatively, you may
try to login using your OpenID. (On 2015-04-27 I have logged in successfully with my OpenID
provided by LiveJournal, but I failed to login with OpenID provided by Google. I did not check
other OpenID providers.)

Browsing bugs does not require authentication.

=over

=item *

L<Report bugs|https://rt.cpan.org/Public/Bug/Report.html?Queue=Software-License-OrLaterPack>

=item *

L<Browse bugs|https://rt.cpan.org/Public/Dist/Display.html?Name=Software-License-OrLaterPack>

=back

CPAN web page also says:

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

However, I did not try this yet.

=head2 Bug tracker at SourceForge

You need a SourceForge account in order to report bugs.

=over

=item *

L<Tickets|https://sourceforge.net/p/orlaterpack/tickets/>

=back

=cut
=pod

=encoding UTF-8

=head1 GLOSSARY

=over

=item CPAN

Comprehensive Perl Archive Network, a B<large> collection of Perl software and documentation. See
L<http://www.cpan.org>.

=item Distribution

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

=item Module

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

=item Package

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

=back

=cut
=pod

=encoding UTF-8

=head1 SEE ALSO

=over

=item L<Dist::Zilla>

=item L<Software::License>

=item L<Why should programs say âVersion 3 of the GPL or any later versionâ?|https://www.gnu.org/licenses/gpl-faq.html#VersionThreeOrLater>

=back

=cut
=pod

=encoding UTF-8

=head1 COPYRIGHT AND LICENSE

Copyright Â© 2015 Van de Bugger

C<Software-License-OrLaterPack> is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software Foundation, either
version 3 of the License, or (at your option) any later version.

C<Software-License-OrLaterPack> is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
Software-License-OrLaterPack.  If not, see <http://www.gnu.org/licenses/>.

C<Software-License-OrLaterPack> I<distribution> may contain files generated by C<Dist-Zilla> and/or
its plugins from third-party templates; copyright and license specified above are I<not> applicable
to that files.

=cut


# end of file #
