distmgr - Manage a Perl distribution

• Description
• Configuration
• Limitations
• Usage
• Commands
  • create - Create distribution with repository
  • dist - Create a distribution
  • release - Release a distribution
  • cycle - Prepare next development cycle
  • install - Install individual features
  • config - Create a default configuration file
• Examples
• Command Process Flows
  • create
  • dist
  • release
  • cycle
  • install

Description

The distmgr command line application that's installed along with the Dist::Mgr Perl distribution provides the facility to manage Perl distributions that you're the author of.

It allows you to create distributions (with or without a Github repository), release your distributions, automatically prepare your distribution's next development cycle, and install some or all of the features and files that we provide.

Configuration

Some command line arguments can be configured in a configuration file. See the config command section for details.

Limitations

Due to this software being early in its life, we have some limitations currently

• Github is the only Version Control platform that we support
• You must create an empty Github repository through their site prior to VCS operations being executed
• You must have git installed for VCS functionality to be executed
• Github Actions is the only CI platform we support
• Coveralls.io is the only test coverage platform we support
• Github is the only bugtracker platform we support
• ExtUtils::MakeMaker is the only build system we support

Usage

distmgr <command> [OPTIONS]

Commands

create

This command creates a new distribution with all features enabled. Before using this command, you must create an empty Github repository through their site which we'll clone and insert the distribution's files into. We will include:

• A base distribution skeleton, modelled around one created with module-starter from Module::Starter
• bugtracker and repository information
• CI and test coverage badges
• Pre-populated .gitignore file
• Pre-populated MANIFEST.SKIP file
• Pre-populated Github Actions CI configuration file

Options

-m | --module   Mandatory: The module name (eg. Test::Module)
-a | --author   Mandatory: The name of the author (eg. "Steve Bertrand")
-e | --email    Mandatory: The email address of the author
-u | --user     Optional:  The Github username (eg. stevieb9)
-r | --repo     Optional:  The Github repository name (eg. test-module)
-V | --verbose  Optional:  (Flag) Display verbose output for each process
-h | --help     Optional:  (Flag) Display help

dist

This command is similar to create, but does not include any VCS or CI 'fluff'. It creates a simple distribution skeleton, nothing more.

Options

-m | --module   Mandatory: The module name (eg. Test::Module)
-a | --author   Mandatory: The name of the author (eg. "Steve Bertrand")
-e | --email    Mandatory: The email address of the author
-h | --help     Optional:  (Flag) Display help
-V | --verbose  Optional:  (Flag) Display verbose output for each process

release

This command performs a release of your distribution. The following actions are performed (Git/CI operations are only executed if you're in a repository directory):

• Set the current date in the Changes file
• Run a local make test
• Commit and Push to Github, and execute remote CI test and coverage
• Create a distribution tarball
• Git tag the state of the repository with the release version
• Push the new tag
• Upload the distribution tarball to the CPAN

Options

-i | --cpanid   Optional:  Your PAUSE userid
-p | --cpanpw   Optional:  Your PAUSE userid's password
-d | --dryrun   Optional:  (Flag) Don't actually upload to the CPAN
-V | --verbose  Optional:  (Flag) Display verbose output for each process
-w | --wait     Optional:  (Flag) Wait for CI tests to finish (--nowait to disable)
-h | --help     Optional:  (Flag) Display help

Note: The --cpanid and --cpanpw can be omitted if you set the CPAN_USERNAME and CPAN_PASSWORD environment variables prior to script run.

cycle

This command is run after release, and prepares your distribution/repository for your next development cycle. We:

• Bump the version (by 0.01) in the Changes file
• Bump the version in all of your distribution's module files
• Perform Git commit and push actions

Options

-h | --help     Optional:  (Flag) Display help

install

This command allows you to install the files and features of this software into an already-existing distribution that you author.

Options

All the options listed below are optional.

-g | --gitignore    Install .gitignore file
-c | --ci           Install Github Actions CI configuration file
-B | --badges       Insert CI/Coverage badges links into the module's POD
-b | --bugtracker   Insert bugtracker information into Makefile.PL
-R | --repository   Insert repository information into Makefile.PL
-h | --help         Display help

-A | --all          Insert/Install all above options

config

Creates an initial, default configuration file.

This file will be named dist-mgr.json and will be placed in your HOME directory on Unix systems, and in your USERPROFILE directory on Windows.

Examples

• Create with repository

    distmgr create \
            --module Test::Module \
            --author "Steve Bertrand" \
            --email  steveb@cpan.org \
            --repo   test-module \
            --user   stevieb9

• Create without repository

    distmgr dist \
            -m Test::Module \
            -a "Steve Bertrand" \
            -e steveb@cpan.org

• Release an existing distribution

    distmgr release \
            --cpanid STEVEB
            --cpanpw password

• Prepare distribution for next development cycle

    distmgr cycle

• Implement Dist::Mgr features into an existing distribution

    distmgr install \
            --gitignore \
            --ci \
            --badges \
            --bugtracker \
            --repository 
            
    # or
    
    distmgr install --all

• Create an initial default configuration file

    distmgr config

Command Process Flows

create process

• Create the distribution skeleton from an empty repository or new directory. For Github integration, you must create a new empty repository on Github, then supply its short name with the --repo argument along with the --user argument.

• Remove files that we don't deem necessary for the distribution

• Add a custom Changes file, formatted to a standard that is understood to this software

• Add a MANIFEST.SKIP file

• Add a custom t/manifest.t test file

• Add a custom .gitignore file (requires --user and --repo)

• Add a default Github Actions Continuous Integration configuration file (requires --user and --repo)

• Add bugtracker and repository meta information to Makefile.PL, which allows this information to be presented on the CPAN (requires --user and --repo)

• Perform a git add ., then git commit and finally git push (requires --user and --repo)

dist process

• Create a base distribution skeleton within a directory that is representative of the module name you've sent in. Other than custom Changes, MANIFEST.SKIP, t/manifest.t files, the skeleton is pretty well exactly like a distribution created by module-starter from the Module::Starter distribution

release process

• Enable git interaction if A) git is installed, B) --repo and --user are sent in

• Set the date in the Changes file for the current version we're about to release

• Updates POD Copyright year, if applicable

• Perform a make manifest to update the MANIFEST file

• Run a make test and halt progress if any test fails

• Run a git commit and git push if anything has changed and git interaction is enabled

• Present the user for a prompt while we wait for CI testing to complete. You must manually check your Github Actions progress while we wait. When CI testing is complete, you press CNTRL-C to inform us of success, or ENTER to indicate CI failure. If you signify failure, we'll halt all further processing. Git must be enabled for these steps.

• Run a make dist to generate the distribution tarball that gets sent to the CPAN

• Upload the new distribution to the CPAN via Pause::Uploader. This process will not take place unless the --cpanid and --cpanpw are supplied, or the CPAN_USERNAME and CPAN_PASSWORD environment variables are populated

• Run a make distclean to clean up the distribution directory

• Perform a git tag with the version number of this release (requires Git to be enabled)

• Perform a git push --tags to push the new tag to Github (requires Git enabled)

cycle process

• Enable git interaction if A) git is installed, B) --repo and --user are sent in

• Increment the version number of all module files found by 0.01

• Add a new section into the Changes file, with the updated version and an unreleased indicator

• git commit and git push these changes, if git interaction is enabled

install process

• Inserts sections into specific files for new features, or installs files for updated functionality