The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Dist-Mgr-1.04
River stage zero No dependents
++
/ Dist::Mgr

NAME

Dist::Mgr - Automation for Perl distribution creation, integration, pre-release, release and post-release tasks.

Coverage Status

DESCRIPTION

For end-users, please review the documentation for the distmgr program that we've installed for you as part of this distribution.

This software performs a full suite of automated creation, addition, pre-release, release and post release tasks for Perl distributions. It integrates with VCS, automates the configuration of Continuous Integration, manages version numbers and Changes files, amongst a slew of other tasks.

This distribution is essentially a bunch of tools that revolve around a base distribution created with module-starter.

At this time, it relies on using Module::Starter for initial distribution creation, Github for repository and bugtracker, and the ExtUtils::MakeMaker build system, which utilizes Makefile.PL files.

SYNOPSIS

    use Dist::Mgr qw(:all)

    ...

EXPORT_OK

We do not automatically import anything into your namespace, you must request functionality explicitly. Use the :all tag, or have a peruse through the "FUNCTIONS" section for what's available.

FUNCTIONS

add_bugtracker

Adds bugtracker information to the Makefile.PL file. If the required META_MERGE section doesn't exist, we'll create it.

Currently, only Github is supported.

Use: After "init", or any time.

Parameters:

    $author

Mandatory, String: The Github username of the software author. For example, mine is stevieb9.

    $repository

Mandatory, String: The name of the repository. For example, the repository name for this distribution is dist-mgr.

    $makefile

Optional, String: The path and name of the Makefile.PL file to use. We default to ./Makefile.PL.

Returns: 0 upon success.

add_repository

Adds repository information to the Makefile.PL file. If the required META_MERGE section doesn't exist, we'll create it.

Currently, only Github is supported.

Use: After "init", or any time.

Parameters:

    $author

Mandatory, String: The Github username of the software author. For example, mine is stevieb9.

    $repository

Mandatory, String: The name of the repository. For example, the repository name for this distribution is dist-mgr.

    $makefile

Optional, String: The path and name of the Makefile.PL file to use. We default to ./Makefile.PL.

Returns: 0 upon success.

changes

Creates or updates the initial Module::Starter Changes file to my custom standard format.

Use: After "init".

Parameters:

    $module

Mandatory, String: The name of the module (eg. Acme::STEVEB).

    $file

Optional, String: The path and name of the Changes file to operate on. By default, we operate on the Changes file within the current working directory, ..

Returns: The contents that were added into the file.

changes_bump

Prepares the Changes file for a new development cycle after a release.

Use: After "changes_date" and the release has been published.

Parameters:

    $version

Mandatory, Version: A valid Perl version number. Must be higher than the previous release version.

    $file

Optional, String: The name of the Changes file to operate on. Defaults to the one in the current working directory.

changes_date

Replaces the UNREL tag with today's date, in preparation of a release.

Use: As part of the release cycle, before release and "changes_bump".

Parameters:

    $file

Optional, String: The name of the Changes file to operate on. By default, we operate on the one in the current working directory.

ci_badges

Inserts various CI and coverage badges into module files.

Use: After "init", or any time.

Parameters:

    $author

Mandatory, String: The repository owner (eg. mine is 'stevieb9').

    $repository

Mandatory, String: The name of the repository (eg. this one is 'dist-mgr').

    $fs_entry

Optional, String: The path and name of a Perl module file, or a directory that contains Perl module files. If a directory is sent in, we'll operate recursively.

Returns: 0 upon success.

ci_github

Installs a Github Actions configuration file into .github/workflows. We'll create the directory if it doesn't exist.

Use: Any time.

Parameters:

    $os

Optional, Array Reference: A list of the Operating Systems you want to run your tests on.

Valid values: l, w, m, where:

    l == Linux (Ubuntu to be specific)
    w == Windows
    m == MacOS

Defaults: Test suite will be run on Operating Systems ubuntu-latest, windows-latest, macos-latest. Each OS will run the tests on Perls 5.32, 5.24, 5.18, 5.14 and 5.10.

Returns: An array of the contents of the generated file.

config

Writes out a default configuration file if one doesn't exist, and updates the %args hash within a function.

Parameters:

    \%args

Mandatory, Hash reference: Send in a reference to your %args hash, and we'll update it with any directives within the configuration file before you send them off to other various routines.

    $file

Optional, String: The name of an alternate configuration file you'd like to write out, or read from. Default is $ENV{USERPROFILE}/dist-mgr.json on Windows systems, and $ENV{HOME}/dist-mgr.json on Unix systems.

Returns: The reference to the %args hash you sent in as the first parameter.

config_file

Returns the path and filename of the default configuration file. this is $ENV{USERPROFILE}/dist-mgr.json on Windows systems, and $ENV{HOME}/dist-mgr.json on Unix systems.

Finds and updates the copyright year of a Perl POD or module file, or all Perl files in a directory structure. We operate on all *.pl, *.pm and *.pod files.

Use: Before publishing a release.

Parameters:

    $fs_entry

Optional, String: The name of a file or directory to work on. If a directory, we'll work on all Perl and POD files. Defaults to ..

Returns: A hash reference with the file name as the key, and the updated year as the value.

Fetches the current copyright year in a file or all files in a directory. We operate on all *.pl, *.pm and *.pod files.

Use: Anytime.

Parameters:

    $fs_entry

Optional, String: The name of a file or directory to work on. If a directory, we'll work on all Perl and POD files. Defaults to ..

Returns: A hash reference with the file name as the key, and the current copyright year as the value.

cpan_upload

Uploads the distribution tarball to PAUSE.

Use: After "make_dist".

Parameters:

    $tarball_name

Mandatory, String: The name of the distribution's tarball file.

    %args

Optional, Hash: See CPAN::Uploader for full details. A couple of notes:

The user and password parameters can be set in the CPAN_USERNAME and CPAN_PASSWORD environment variables instead of passing them in with the hash.
You can add dry_run => 1 to the hash to skip the actual upload process.

Returns: Copy of %args hash on success.

git_add

Adds all files in the current working directory to the repository.

Note: Calls Dist::Mgr::Git::_git_add() internally.

Use: Any time.

Parameters: $verbose

Optional, Bool: Set to true to display the Git command output. Defaults to false.

Returns: Exit code from the system call.

git_ignore

Generates a .gitignore file.

Use: Any time.

Parameters:

    $directory

Optional, String: The directory where we'll create the file. If not specified, we'll create it in the current directory, ..

Returns: An array of the file's contents.

git_commit

Commits all changes to the repository.

Note: Calls Dist::Mgr::Git::_git_commit() internally.

Use: Any time.

Parameters:

    $msg

Mandatory, String: The commit message.

    $verbose

Optional, Bool: Set to true to display the Git command output. Defaults to false.

Returns: Exit code.

git_clone

Commits all changes to the repository.

Note: Calls Dist::Mgr::Git::_git_clone() internally.

Use: Any time.

Parameters:

    $author

Mandatory, String: Your Github username.

    $repository

Mandatory, String: The name of the pre-created Github repository.

    $verbose

Optional, Bool: Set to true to display the Git command output. Defaults to false.

Returns: Exit code.

git_push

Pushes the repository to Github.

Note: Calls Dist::Mgr::Git::_git_push() internally.

Use: Any time.

Parameters:

    $verbose

Optional, Bool: Set to true to display the Git command output. Defaults to false.

Returns: Exit code.

git_pull

Does a git pull to fetch any update from the upstream.

Note: Calls Dist::Mgr::Git::_git_pull() internally.

Use: Any time.

Parameters:

    $verbose

Optional, Bool: Set to true to display the Git command output. Defaults to false.

Returns: Exit code.

git_release

Commits and pushes the repository, and executes the CI test pipeline (if available).

Internally, this method calls "git_pull", "git_commit" then "git_push", all with their respective $verbose flags set to false. If you want to enable verbosity, instead of calling this function, call each one of those in order and set $verbose to true in each one.

Use: After "make_test".

Parameters:

    $version

Mandatory, String: The release version of the distribution.

    $wait_for_ci

Optional, Bool: Whether to wait for keyboard interaction while CI testing runs. If set, we'll wait for you to press either CTRL-C to signifiy tests were successful and we should continue with the release cycle, or ENTER to signify that we should stop and wait for you to fix any test errors before running again.

Default: 1, Enabled.

Returns: 1 on test success (CTRL-C), 0 on test failure (ENTER).

git_repo

Attempts to retrieve the repository name from the .git directory.

Note: Calls Dist::Mgr::Git::_git_repo() internally.

Use: Any time.

Returns: The string repository name on success, the exit code on failure.

git_status_differs

Checks whether we need to commit and push.

Note: Calls Dist::Mgr::Git::_git_status_differs() internally.

Use: Any time.

Returns: 1 if the repository differs and 0 if nothing needs to be done.

git_tag

Tags the current state of the repository.

Parameters:

    $tag

Mandatory, String: The tag for the commit.

Note: Calls Dist::Mgr::Git::_git_tag() internally.

Use: Any time.

Returns: Exit code.

init

Initializes a new distribution using Module::Starter. The new directory will be placed into the current working directory (.).

Use: To create a brand new distribution skeleton.

Parameters:

    module  => "Acme::STEVEB"

Mandatory, String: The name of the main module of the distribution.

    author  => "Steve Bertrand"

Mandatory, String: The name of the distribution's author.

    email  => "steveb@cpan.org"

Mandatory, String: The email address of the author.

    license  => "artistic2"

Optional, String: The license to apply to the new distribution. Defaults to artistic2. See Module::Starter for valid entries.

    verbose => 1

Optional, Bool: If set, we'll display the progress of module creation.

make_dist

Perform a make dist that creates a CPAN-ready distribution tarball file in the current working directory.

Use: After all other release functions have been called.

Parameters:

    $verbose

Optional, Bool: Set to true to display the output from the command.

Default: False

Returns: 0 on success. Anything other than 0 is a failure.

make_distclean

Perform a make distclean on the project directory.

Use: After all other post-release functions have been called.

Parameters:

    $verbose

Optional, Bool: Set to true to display the output from the command.

Default: False

Returns: 0 on success. Anything other than 0 is a failure.

make_test

Perform a %^X Makefile.PL and make test.

Use: After "changes_date" and before all other release cycle functions.

Parameters:

    $verbose

Optional, Bool: Set to true to display the output from the command.

Default: False

Note: Do not call this function from within the test suite, or else it'll spin off into an infinite loop.

Note: Always check the return value of this function before proceeding with the rest of the release cycle. Zero 0 is success, everything else is fail.

Returns: 0 on success. Anything other than 0 is a failure.

make_manifest

Perform a make manifest.

Use: Before running the release procedures.

Parameters:

    $verbose

Optional, Bool: Set to true to display the output from the command.

Default: False

Returns: 0 on success. Anything other than 0 is a failure.

manifest_skip

Generates a MANIFEST.SKIP file.

Use: Any time.

Parameters:

    $directory

Optional, String: The directory where we'll create the file. If not specified, we'll create it in the current directory, ..

Returns: An array of the file's contents.

manifest_t

Generates a t/manifest.t test file. This overrides the default created with Module::Starter, as some custom MANIFEST.SKIP entries fail with the older version of the file.

Use: Any time.

Parameters:

    $directory

Optional, String: The directory where we'll create the file. If not specified, we'll create it in the t/ directory within the current directory, ..

Returns: An array of the file's contents.

move_distribution_files

After an "init", this method will scoop up all of the files and directories from within the newly created temp module directory into the current working dir, then remove the temp module directory.

Use: Immediately after "init".

Parameters:

    $module

Mandatory, String: The name of the module that was created with "init", eg. Acme::STEVEB.

Returns: 0 upon success.

remove_unwanted_files

Removes unwanted file system entries. We always operate from the perspective of the current working directory (.).

Use: Immediately after "init" and "move_distribution_files".

version_bump

Finds and updates the version number of a Perl module file, or all Perl module files in a directory structure.

Use: After publishing a release.

Parameters:

    $version

Mandatory, String: The new version to update to.

    $fs_entry

Optional, String: The name of a file or directory to work on. If a directory, we'll work on all Perl module files. Defaults to lib/.

Dry run mode

The $version parameter can be prepended with an optional dash (-), and if so, we'll operate in "dry-run" mode, where we'll return the results, but won't have written to any files. Eg: version_bump('-1.01').

Returns: An HoH:

    $VAR1 = {
        't/data/work/Two.pm' => {
            'dry_run'   => 0,
            'from'      => '2.66',
            'to'        => '2.67',
            'content'   => '' # Module file code (snipped for brevity)
        },
        't/data/work/One.pm' => {
            'dry_run'   => 0,
            'from'      => '2.66',
            'to'        => '2.67',
            'content'   => '' # Module file code (snipped for brevity)
        },
    };

version_incr

Increments a version number by 0.01, and returns the result.

Use: Any time

Parameters:

    $version

Mandatory, String: A valid version number (eg: 1.03).

Returns: The supplied version number incremented by 0.01.

version_info

Fetches the file version information of Perl module files. Can operate on a single file, or iterate over a directory structure.

Use: Any time.

Parameters:

    $fs_entry

Optional, String: The directory or file to operate on. If a directory is sent in, we'll iterate over all files in all directories recursively.

Default: lib/

Returns: Hash reference:

    $VAR1 = {
        't/data/orig/One.pm'    => '2.66'
        't/data/orig/Two.pm'    => '2.66',
        't/data/orig/Three.pm'  => '2.66',
        't/data/orig/Bad.pm'    => undef,   # $VERSION can't be parsed
        't/data/orig/No.pm'     => undef,   # No $VERSION defined
    };

AUTHOR

Steve Bertrand, <steveb at cpan.org>

LICENSE AND COPYRIGHT

Copyright 2020-2021 Steve Bertrand.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0