RELEASE(1) User Contributed Perl Documentation RELEASE(1) NAME release - give your Perl distros to the world SYNOPSIS release [OPTIONS] [ LOCAL_FILE [ REMOTE_FILE ] ] # print a help message and exit release -h # try a dry run without uploading anything release -t # skip dist while checking release -D # skip kwalitee testing (e.g. a script distro) release -k # print debugging information release -d # print release number and exit release -v # set $ENV{AUTOMATED_TESTING} to a true value release -a # Enable parallel testing by setting $ENV{HARNESS_OPTIONS} release -j release -j8 DESCRIPTION This is the prototype program for using "Module::Release". You should mod- ify it to fit your needs. If it doesn't do what you want, you can change it however you like. This is how I like to release my modules, and I'm happy to add features that do not get in my way. Beyond that, you should write your own script to match your process. This program automates Perl module releases. It makes the distribution, tests it, checks that source control is up to date, tags source control, and uploads it to the PAUSE. By default this script assumes that you use Git as your source control and relies mostly on Module::Release::Git, which is an external module. This distributes Module::Release::SVN, but I haven't touched that in years. There's still some code for CVS that I should probably rip out. Process The release script checks many things before it actually releases the file. Some of these are annoying, but they are also the last line of defense against releasing bad distributions. Read the configuration data Look in the current working directory for ".releaserc". See the Con- figuration section. If release cannot find the configuration file, it dies. Various sanity checks These are related to various mistakes I've made at some point. * am I allowed to release from this branch (so, not an experimental branch) * have I listed all the prereqs? * is the version greater than what I've already released? Test and make the distribution Run make realclean, perl Makefile.PL, make test, make dist, make disttest. If testing fails, release dies. make dist provides the name of the distribution if LOCAL_FILE is not provided on the command line. Too test the distribution against several perl binaries, see the "perls" configuration setting. Check that source control is up-to-date If there are modified files, added files, or extra files so that source control complains, fail. Check that any GPG signatures are correct If "gpg_signatures" is present in the config, load Module::Re- lease::VerifyGPGSignature and verify the configured signatures. Upload to PAUSE This program used to use FTP uploads, but PAUSE has turned off that feature. Now it uploads through the web form. Tag the repository Use the version number (in the distribution name) to tag the reposi- tory. You should be able to checkout the code from any release. Command-line switches -a --automated-testing Set $ENV{AUTOMATED_TESTING} to true. You can also set "automated_test- ing" in the configuration file -c STRING --changes STRING Specify the Changes file entry on the command line. If STRING does not start with a "*", one will be added to the start along with a space. release -c "* some change" translates to the Changes entry with the date and one bullet item: 3.11 2025-02-20T22:56:28Z * some change STRING can also be a multiline string, but this will only append a "*" to the first line if it does not already have on. All lines will be in- dented under the date though. -C --skip-changes Skip the Changes file. This is also the "skip_changes" config option -d --skip-debug Show debugging information. This is also the "debug" config option -D --skip-dist Skip building the dist. This is also the "skip_dist" config option -h -? --help --usage Print a help message then exit -j [#] --jobs[=#] Enable parallel testing by defining the number of jobs Test::Harness can execute in parallel by setting $ENV{HARNESS_OPTIONS} to "j#". You can also set "test_jobs" in the configuration file. When not passing a count or count 0, this script will try to use Sys- tem::Info to get the CPU count. If it is not available or returns a false value, the count will default to 9. -k --skip-kwalitee Skip the kwalitee checks. You can also set the "skip_kwalitee" direc- tive to a true value in the configuration file. Have you considered just fixing the kwalitee though? :) -m --skip-manifest Skip the manifest check. You can also set the "skip_manifest" directive to a true value in the configuration file. -p --skip-prereq Skip the prereq checks. You can also set the skip_prereqs directive to a true value in the configuration file. Have you considered just fixing the prereqs though? :) -t --test-only --dry-run Run all checks then stop. Do not change any files or upload the distri- bution -T --skip-tests Skip the tests. This is useful when you just want to upload -v --version Print the program name and version then exit -V --skip-version Skip the version check against CPAN Configuration The release script uses a configuration file in the current working direc- tory. The file name is .releaserc. release's own .releaserc looks like this: cpan_user BDFOY If you would like to test with multiple perl binaries (version 1.21 and later), list them as a colon-separated list in the "perls" setting: perls /usr/local/bin/perl5.6.2:/usr/local/bin/perl5.10.0 release does not test the perls in any particular order. allow_glob_in_perls If true, expand globs in the "perls" configuration. Default: 0 allow_branches A comma-separated list of literal branch names that are allowed to re- lease (requires Module::Release::Git 1.016). allow_branches_regex A Perl pattern to match version control branches that are allowed to release (requires Module::Release::Git 1.016). automated_testing Set "automated_testing" to the value you want for the $ENV{AUTO- MATED_TESTING} setting. By default this is 0, so testing is started in interactive mode. commit_message_format A sprintf format for the message when "release" commits its changes. So far this takes one %s placeholder for the module version (requires Module::Release::Git 1.016). cpan_user The PAUSE user dry_run When true, stop before releasing the dist. This is also the "-t" switch. test_jobs If set, define the number of parallel jobs Test::Harness may use to run the tests. If 0, try to get the CPU count using System::Info. If that is not available or returns a false value, default to 9. perls A colon-separated list of perls to test with. If "allow_glob_in_perls" is a true value, globs in paths will expand to their paths so you can specify many perls. Default: the perl that's running "release". release_subclass DEPRECATED AND REMOVED. You should really just write your own release script. Fork this one even! required An optional list of comma-separated modules that are required to be available. These are checked before building "Makefile". required DBI,Text::CSV_XS,SQL::Statement A list like this can be handy when testing against a lot of perl ver- sions (see "perls" above) in which some do and some do not have all re- quired modules installed. Another good reason to have this is when testing against optional modules. skip_changes Skip updating the changes. This is also the "-C" switch. skip_cpan_version_check Skip comparing the local module version to the previous release ver- sion. This is also the "-V" switch. skip_kwalitee Set to a true value to skip kwalitee checks (such as for a script dis- tribution with no modules in it). This is also the "-k" command-line switch. skip_manifest Set to a true value, it skips checking the MANIFEST file. This is also the "-m" command-line switch. skip_prereqs Set "skip_prereqs" to 1 if you don't want to run the Test::Prereq checks. By default this is 0 and "release" will try to check prerequi- sites. This is also the "-p" command-line switch. skip_tests Set "skip_tests" to 1 if you don't want to run any of the tests. This is also the "-T" command-line switch. Environment * AUTOMATED_TESTING Module::Release doesn't do anything with this other than set it for Test::Harness. * CPAN_PASS release reads the "CPAN_PASS" environment variable to set the password for PAUSE. Of course, you don't need to set the password for a system you're not uploading to. * CPAN_PASS_<USER> Append the CPAN user ID to "CPAN_PASS" and use that value to interact with PAUSE. This allows people to deal with more than one CPAN account (for example, work and personal). If this has no value, it is used preferentially to "CPAN_PASS" * RELEASE_DEBUG The "RELEASE_DEBUG" environment variable sets the debugging value, which is 0 by default. Set "RELEASE_DEBUG" to a true value to get de- bugging output. * PERL The "PERL" environment variable sets the path to perl for use in the make; otherwise, the perl used to run release will be used. * RELEASE_OPTS A string representing options to add to the command line. TO DO * break out functional groups into modules. * more plugins! SOURCE AVAILABILITY This source is in GitHub as part of the Module::Release project: https://github.com/briandfoy/module-release AUTHOR brian d foy, "<briandfoy@pobox.com>" COPYRIGHT AND LICENSE Copyright A(C) 2002-2025, brian d foy <briandfoy@pobox.com>. All rights re- served. You may use this software under the same terms as Perl itself. CREDITS Ken Williams turned the original release(1) script into a module. Andy Lester contributed to the module and script. H. Merijn Brand submitted patches to work with 5.005, to create the auto- mated_testing and required features and parallel testing. perl v5.42.3 2025-12-12 RELEASE(1)
NAME | SYNOPSIS | DESCRIPTION | TO DO | SOURCE AVAILABILITY | AUTHOR | COPYRIGHT AND LICENSE | CREDITS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=release&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>