How To Make A Release

If there hasn't been a release in a while, and you want some new features or bugs, you can make the release! Here's how.

These instructions are for people who have never released a module before from git. Experienced people may wish to substitute in their own tools and procedures but please read the instructions regardless as we may do things differently from what you're used to.

Who can make a release?

Anybody who wants to give it a try can make an alpha release. Really!

Post an issue stating you'd like to make a release

Include what feature or bug you're wanting to make available on CPAN.

What type of release is this, alpha or stable?

Alpha releases can pretty much happen any time by any one.

Stable releases require more thought and have additional procedures.

Do you have a PAUSE account?

PAUSE is the Perl Authors Upload Server... Eh. It's how authors manage their modules on CPAN. You'll need a PAUSE account to upload a CPAN module. Ask them for one. The process is not instant, so get that done as soon as possible.

If this is a stable release, do you have PAUSE permissions for MakeMaker?

Alpha releases do not need PAUSE permissions, but a stable release does.

If you're not sure, you can check but you need a PAUSE account first.

If not, ask for them and we'll get it sorted.

Run git checkout master to get on the master branch.

git pull origin master to make sure you're up to date.

Increment the $VERSION number in all the .pm files in lib.

We have a program for doing this, admin/increment_version.

For an alpha release, run perl admin/increment_version --alpha.

For a stable release, run perl admin/increment_version --stable.

Here's the details of how $VERSION is incremented...

When incrementing an alpha release to the next alpha, increment by _01. 6.65_01 goes to 6.65_02.

When incrementing a stable to alpha, increment by .01_01 so 6.66 goes to 6.67_01. This is because its ambiguous if 6.66 is greater or less than 6.66_01.

When incrementing a stable to a new stable... this should never happen. A stable should always be preceded by an alpha.

Update Changes

You can use the log to find out what's changed. If you're putting out v1.23 you can use git log v1.22..HEAD to see all the changes since the last release.

The changes file is only the changes which may be of interest to users.

• Changes should be broken up into categories
  • New Features - any user visible changes
  • Docs - significant changes to the documentation
  • Bug fixes
  • Test fixes
  • Distribution changes - changes to things which aren't the tests, docs or code
  • Incompatible changes
  • Misc
• Only log interesting changes
• Find changes using "git log"
• If possible, associate each change with a Github or rt.cpan.org issue. Like [github 7] or [rt.cpan.org 23982]
• If possible, attribute each change with the contributor. Like (Jacinta Richardson) or (chocolateboy).

Date the release in Changes.

Include the current version and date of release (use the date command) after the version number. For example...

6.63_04  Thu Nov 22 13:18:06 PST 2012
    Test Fixes
    * Eliminated the problematic and not very useful PASTHRU test
      ...

Get a clean build environment.

To ensure you have a clean build environment and up to date Makefile, write a new Makefile...

perl Makefile.PL

Clean up any temporary or build files...

make realclean

And because realclean includes the Makefile, run perl Makefile.PL again to get a new Makefile to work with.

perl Makefile.PL

Run make manifest to update the MANIFEST.

The MANIFEST is the list of all files in the distribution. It is automatically generated by the make manifest command.

For example...

$ make manifest
/usr/bin/perl "-Iblib/arch" "-Iblib/lib" "-MExtUtils::Manifest=mkmanifest" -e mkmanifest
Added to MANIFEST: .perlcriticrc
Added to MANIFEST: t/liblist/win32/imp.dll.a

Run git diff MANIFEST to make sure nothing weird slipped into the MANIFEST.

If it did, consider updating MANIFEST.SKIP, deleting the MANIFEST and rerunning make manifest.

Verify your changes with git diff.

Congratulations! You've made all the necessary changes. Review them with git diff. There should only be changes to...

• $VERSION in lib files
• MANIFEST
• MANIFEST.SKIP (if you needed to update it)
• Changes

Run make disttest and ensure it passes.

Run make dist to build the tarball.

STOP and THINK

Up to this point, nothing you've done is permanent. This is your last chance to avoid uploading a mistake. That said, if this is an alpha, be bold! If it screws up you can always upload another version with a minimum of disruption.

Did you remember to...

• Checkout the master branch?
• Check you're up to date with git pull origin master?
• Update Changes?
• Date the current release in Changes?
• Increment $VERSION in every .pm file in lib?
• Update the MANIFEST?

Upload the tarball to PAUSE.

Commit all the changes.

This includes the change log, MANIFEST and/or MANIFEST.SKIP changes, etc. Under normal circumstances, no files should be added or removed.

Tag the release with git tag v$VERSION.

Note the v. Version 1.23 is git tag v1.23.

git push origin master to push your changes to Github

git push origin v$VERSION to push your tag to Github

Check for email from PAUSE

PAUSE should send you two emails. One acknowledges a successful upload. One tells you if it was indexed correctly, that is if it verifies you have permission to upload MakeMaker and its sub packages. If the indexing didn't work, you're probably missing permissions. Post an issue and we'll sort it out.

Make an announcement.

Email [email protected] and [email protected]. Include the change log entries since the last stable. Also include a link to the Changes files on metacpan. For example, the Changes file for 6.65_01. Make sure its a link to your version.

You can also announce on any other forum likely to be seen by module authors.

And a Twitter post on hashtag #perl couldn't hurt.

CONGRATULATIONS!

You've just released a CPAN module! Your fame is legion. Your version should appear on MetaCPAN in a few minutes, search.cpan.org will take longer. It will take anywhere from a few minutes to a few days for your new version to show up on CPAN mirrors, depends on the mirror.

Who can change this document and how

Formatting, typos, clarification and other minor changes can be done by anyone without discussion or approval. Its a wiki, edit it.

Changes, additions and deletions to the policy should first be discussed by writing it up as an issue.

We particularly welcome edits and missing steps from people actually attempting to make a release.