WHAT?

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

    Software-License-OrLaterPack is free sotfware.

QUICK START

    Install the distribution:

        $ cpanm Software::License::OrLaterPack

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

        license = GPL_3::or_later

LIST OF PROVIDED LICENSES

    AGPL_3::or_later
    GPL_3::or_later

WHY?

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

        license = NAME

    where *NAME* is a name of module from Software::License hierarchy.

    Software-License is shipped with a set of popular licenses, from Apache_1_1
    to Zlib, including GNU General Public licenses (GPL) GPL_1, GPL_2, GPL_3,
    including their "Lesser" and "Affero" variants (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 dist.ini:

        license = GPL_3

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

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

SOURCE vs DISTRIBUTION

    You may face Software-License-OrLaterPack in *source* or *distribution*
    form.

    If you are going to release *your* Perl distribution under the terms of
    GPLv3+ or AGPLv3+ license, you will likely be interested in *using*
    Software-License-OrLaterPack *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. If you are going to *develop* (or *hack*) the
    Software-License-OrLaterPack itself, you will likely need the *actual
    source*, not distribution.

    How to distinguish source and distribution:

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

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

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

    *   Name of source directory does *not* include version, while name of
        distribution does.

SOURCE

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

    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.

DISTRIBUTION

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

  Generated files

    Distribution may cointain files preprocessed or generated by Dist-Zilla and
    its plugins. Some generated files are made from 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 *XXX* is a name of the plugin generated the file). Such files are
    *not* part of Software-License-OrLaterPack source.

INSTALLING A DISTRIBUTION

  With cpanm

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

  Manually

    To install distribution tarball manually (let us assume you have version
    *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

HACKING THE SOURCE

    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 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 Dist-Zilla plugins are missed, 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 *VERSION* is a version of built distribution.

BROWSING THE DOCUMENTATION

  Online

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

  Locally installed

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

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

  Built from source

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

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

REPORTING BUGS

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

  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.

    *   Report bugs
        <https://rt.cpan.org/Public/Bug/Report.html?Queue=Software-License-OrLat
        erPack>

    *   Browse bugs
        <https://rt.cpan.org/Public/Dist/Display.html?Name=Software-License-OrLa
        terPack>

    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.

  Bug tracker at SourceForge

    You need a SourceForge account in order to report bugs.

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

GLOSSARY

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

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

SEE ALSO

    Dist::Zilla
    Software::License
    Why should programs say “Version 3 of the GPL or any later version”?
    <https://www.gnu.org/licenses/gpl-faq.html#VersionThreeOrLater>

COPYRIGHT AND LICENSE

    Copyright © 2015 Van de Bugger

    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.

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

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


