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 perl5i?

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

Schwern will add the details of how $VERSION is incremented...

Update the Changes file

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.

• Include the current version and date of release (use the date command)
• 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).

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.

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 perl5i and its sub packages. If the indexing didn't work, you're probably missing permissions. Post an issue and we'll sort it out.

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.