release - give your Perl distros to the world
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
This is the prototype program for using
"Module::Release". You should modify 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.
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 Configuration
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.
- 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 repository.
You should be able to checkout the code from any release.
- -a
- Set $ENV{AUTOMATED_TESTING} to true. You can also
set automated_testing in the configuration file.
- -d
- Show debugging information
- -h
- Print a help message then exit
- -k
- Skip the kwalitee checks. You can also set the skip_kwalitee directive to
a true value in the configuration file.
Have you considered just fixing the kwalitee though? :)
- -p
- 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
- Run all checks then stop. Do not change any files or upload the
distribution.
- -T
- Skip the tests. This is useful when you just want to upload.
- -v
- Print the program name and version then exit
- -V
- Skip the version check against CPAN
The release script uses a configuration file in the current working directory.
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 release
(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{AUTOMATED_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
- 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 versions (see "perls" above) in
which some do and some do not have all required modules installed.
Another good reason to have this is when testing against optional
modules.
- skip_kwalitee
- Set to a false value to skip kwalitee checks (such as for a script
distribution with no modules in it).
- 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
prerequisites.
- 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.
- 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 debugging 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.
- break out functional groups into modules.
- more plugins!
This source is in GitHub as part of the Module::Release project:
https://github.com/briandfoy/module-release
brian d foy, "<bdfoy@cpan.org>"
Copyright © 2002-2021, brian d foy <bdfoy@cpan.org>. All rights
reserved.
You may use this software under the same terms as Perl itself.
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 and to create
the automated_testing and required features.