NAME
Module::Release - Automate software releases
SYNOPSIS
use Module::Release;
my $release = Module::Release->new( %params );
# call methods to automate your release process
$release->check_cvs;
...
DESCRIPTION
Module::Release
automates your software release process. It started as a script that automated my (brian) release process, so it has bits to talk to PAUSE (CPAN) and SourceForge, and to use Makefile.PL
and CVS
. Other people have extended this in other modules under the same namespace so you can use Module::Build
, svn
, and many other things.
The methods represent a step in the release process. Some of them check a condition (e.g. all tests pass) and die if that doesn't work. Module::Release
doesn't let you continue if something is wrong. Once you have checked everything, use the upload features to send your files to the right places.
The included release
script is a good starting place. Don't be afraid to edit it for your own purposes.
Configuration
Module::Release
looks at several sources for configuration information.
Perl setup
Module::Release
looks at Config
to get the values it needs for certain operations.
- make
-
The name of the program to run for the
make
steps
Environment variables
- PERL
-
Use this value as the perl interpreter, otherwise use the value in
$^X
- RELEASE_DEBUG
-
Do you want debugging output? Set this to a true value
- SF_PASS
-
Your SourceForge password. If you don't set this and you want to upload to SourceForge, you should be prompted for it. Failing that, the module tries to upload anonymously but cannot claim the file for you.
- CPAN_PASS
-
Your CPAN password. If you don't set this and you want to upload to PAUSE, you should be prompted for it. Failing that, the module tries to upload anonymously but cannot claim the file for you.
.releaserc
Module::Release
looks for either .releaserc
or releaserc
in the current working directory. It reads that with ConfigReader::Simple
to get these values:
- release_subclass
-
The subclass of
Module::Release
that you want to use. This allows you to specify the subclass via a .releaserc file; otherwise you wouldn't be able to use therelease
script because theModule::Release
class name is hard-coded there. - makefile_PL
-
The name of the file to run as Makefile.PL. The default is
"Makefile.PL"
, but you can set it to"Build.PL"
to use aModule::Build
-based system. - makefile
-
The name of the file created by
makefile_PL
above. The default is"Makefile"
, but you can set it to"Build"
forModule::Build
-based systems. - cpan_user
-
Your PAUSE user id.
- sf_user
-
Your SourceForge account (i.e. login) name.
- passive_ftp
-
Set this to a true value to enable passive FTP.
- sf_group_id
-
The Group ID of your SourceForge project. This is a numeric ID given to the project usually, and you can see it in the URLs when you browse the SourceForge files area.
- sf_package_id
-
The Package ID of your SourceForge package. This is a numeric ID given to a particular file release, and you can see it in the URLs when you browse the SourceForge files area.
- sf_release_match
-
This is a regular expression. Given the file release name that
Module::Release
picks (e.g. "Foo-Bar-1.15.tgz"), you can run a substitution on it. The replacement string is insf_release_replace
. - sf_release_replace
-
This is a regular expression. Given the file release name that
Module::Release
picks (e.g. "Foo-Bar-1.15.tgz"), you can run a substitution on it. The regex portion is insf_release_match
. - sf_type_id 5002
-
The distribution type (e.g. "gzipped source") of the package, by numeric ID that you have to look up on your own from the SourceForge form. The default is 5002 (".gz source").
- sf_processor_id
-
The processor type (e.g. Intel Pentium) of the package, by numeric ID that you have to look up on your own from the SourceForge form. The default is 8000 ("Any").
Methods
If you don't like what any of these methods do, override them in a subclass.
- new()
-
Create a Module::Release object. Any arguments passed are assumed to be key-value pairs that override the default values.
- config
-
Get the configuration object. By default this is a
ConfigReader::Simple
object; - debug
-
Get the value of the debugging flag.
- debug_on
-
Turn on debugging
- debug_off
-
Turn off debugging
- ua
-
Get the value of the web user agent.
- clean
-
Run `make realclean`
- build_makefile()
-
Runs `perl Makefile.PL 2>&1`.
This step ensures that we start off fresh and pick up any changes in
Makefile.PL
. - test()
-
Run `make test`. If any tests fail, it dies.
- dist()
-
Run `make dist`. As a side effect determines the distribution name if not set on the command line.
- dist_test
-
Run `make disttest`. If the tests fail, it dies.
- dist_version
-
Return the distribution version ( set in dist() )
- dist_version_format
-
Return the distribution version ( set in dist() )
# XXX make this configurable
- check_manifest
-
Run `make manifest` and report anything it finds. If it gives output, die. You should check
MANIFEST
to ensure it has the things it needs. If files that shouldn't show up do, put them in MANIFEST.SKIP.Since `make manifest` takes care of things for you, you might just have to re-run your release script.
- check_cvs
-
Run `cvs update` and report the state of the repository. If something isn't checked in or imported, die.
- check_for_passwords
-
Get passwords for CPAN or SourceForge.
- ftp_upload
-
Upload the files to the FTP servers
- pause_claim
-
Claim the file in PAUSE
- cvs_tag
-
Tag the release in local CVS. The tag name comes from
make_cvs_tag
. - make_cvs_tag
-
By default, examines the name of the remote file (i.e. Foo-Bar-0.04.tar.gz) and constructs a CVS tag like
RELEASE_0_04
from it. Override this method if you want to use a different tagging scheme. - sf_user( [ SF_USER ] )
-
Set or GET the SourceForge user name
- sf_login
-
Authenticate with Sourceforge
- sf_qrs()
-
Visit the Quick Release System form
- sf_release()
-
Release the file to Sourceforge
- get_readme()
-
Read and parse the README file. This is pretty specific, so you may well want to overload it.
- get_changes()
-
Read and parse the Changes file. This is pretty specific, so you may well want to overload it.
- run
-
Run a command in the shell.
- run_error
-
Returns true if the command ran successfully, and false otherwise. Use this function in any other method that calls run to figure out what to do when a command doesn't work. You may want to handle that yourself.
- getpass
-
Get a password from the user if it isn't found.
TO DO
* What happened to my Changes munging?
CREDITS
Ken Williams turned my initial release(1) script into the present module form.
Andy Lester handled the maintenance while I was on my Big Camping Trip. He applied patches from many authors.
Andreas Koenig suggested changes to make it work better with PAUSE.
Chris Nandor helped with figuring out the broken SourceForge stuff.
SOURCE AVAILABILITY
This source is part of a SourceForge project which always has the latest sources in CVS, as well as all of the previous releases. This source now lives in the "Module/Release" section of the repository, and older sources live in the "release" section.
http://sourceforge.net/projects/brian-d-foy/
If, for some reason, I disappear from the world, one of the other members of the project can shepherd this module appropriately.
AUTHOR
brian d foy, <bdfoy@cpan.org>
COPYRIGHT
Copyright (c) 2002-2006 brian d foy. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.