The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Module-Release-1.16
River stage one • 4 direct dependents • 4 total dependents
5 ++
/ Module::Release

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 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 the release script because the Module::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 a Module::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" for Module::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 in sf_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 in sf_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.

check_kwalitee()

Run `cpants_lints.pl distname.tgz`. If it doesn't see "a 'perfect' distribution" it dies.

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 SVN, 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 AND LICENSE

Copyright (c) 2002-2007 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.