NAME

release - upload files to the CPAN and SourceForge.net

SYNOPSIS

release [ LOCAL_FILE REMOTE_FILE ]

DESCRIPTION

This program automates Perl module releases. It makes the distribution, tests it, checks that CVS is up to date, tags CVS, uploads it to the PAUSE anonymous FTP directory and to the incoming directory for SourceForge.net, claims it on PAUSE for your CPAN account, and releases it on SourceForge.net.

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 Configuration section. If release cannot find the configuration file, it dies.

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.

Check that CVS is up-to-date

You can release a file without CVS being up-to-date, but this script also tags the repository with the version number of the release, so it insists on CVS being up-to-date. It fails otherwise.

Upload to PAUSE and SourceForge.net

Simply drop the distribution in the incoming/ directory of these servers.

Claim the file on PAUSE

Connect to the PAUSE web thingy and claim the uploaded file for your CPAN account.

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.

Release to SourceForge.net

The release name is the distribution name without the .tar.gz. The file name is the distribution name. SourceForge.net divides things into projects (with project IDs) and packages within the project (with package IDs). Specify these in the configuration file.

Configuration

The release script uses a configuration file in the current working directory. The file name is .releaserc. Although most of the information is the same for all of your projects, the sf_package_id is probably different. You can get the sf_package_id from the data in the Quick Release Form.

release's own .releaserc looks like this:

    sf_user petdance
    sf_group_id 36221
    sf_package_id 56559
    cpan_user PETDANCE

cpan_user

sf_user

If cpan_user or sf_user is set to <none>, the program will skip releasing for that system. You must release for at least one system.

sf_group_id

sf_package_id

sf_processor_id

sf_type_id

sf_release_match

sf_release_replace

To find sf_package_id and sf_group_id, go to the Add/Edit Release page for your project. The link for "[Add Release]" might look something like this (this is the link for the release package itself):

    https://sourceforge.net/project/admin/newrelease.php?package_id=56559&group_id=36221

so sf_package_id is 56559 and sf_group_id is 36221.

sf_processor_id and sf_type_id are optional, and default to "Any" and "Source .gz". See the HTML in a file release form on SourceForge.net for other options.

sf_release_match and sf_release_replace are for defining the release name, if you don't like the default. For example, the default would set the name for this program to something like "release-0.10". But if you want the name to be only the version number, set sf_release_match=^.+-([\d.]+)$ and sf_release_replace=$1.

passive_ftp

Set passive_ftp to "y" or "yes" for passive FTP transfers. Usually this is to get around a firewall issue.

release_subclass

Specify the name of a subclass to use instead of Module::Release. The subclass can override any of the Module::Release methods. This makes it possible to maintain your own local releasing procedures. For instance, one such subclass might look like this:

  package Module::Release::KWILLIAMS;
  use base qw(Module::Release);
  
  sub make_cvs_tag {
    my $self = shift;
    (my $version) = $self->{remote} =~ / - (\d[\w.]*) \.tar \.gz $/x;
    $version =~ s/[^a-z0-9_]/_/gi;
    return "release-$version";
  }
  1;

To use this subclass, you'd put it in your @INC somewhere, then set release_subclass to Module::Release::KWILLIAMS.

Environment

• CPAN_PASS

• SF_PASS

  release reads the CPAN_PASS and SF_PASS environment variables to set the passwords for PAUSE and SourceForge.net, respectively. 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.

TO DO

• check make disttest (to catch MANIFEST errors) -- needs error catching and reporting

SOURCE AVAILABILITY

This source is part of a SourceForge.net project which always has the latest sources in CVS, as well as all of the previous releases.

        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 software appropriately.

AUTHOR

brian d foy, <bdfoy@cpan.org> and Andy Lester, <andy@petdance.com>

COPYRIGHT

Copyright 2002-2003, brian d foy, All rights reserved.

You may use this software under the same terms as Perl itself.