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 a 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.

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.

Do you have PAUSE permissions for perl5i?

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

Run perl admin/change_version X.Y.Z to change the version.

perl5i follows Semantic Versioning 2.0 (minus section 10 and 11 because Perl does alpha versions its own way).

You are probably not incrementing X, it is for backwards incompatible changes.

If there is a new feature this release, increment Y and Z is set to 0.

If there are only bug fixes this release, only increment Z.

For example, a release with new features and bug fixes would go from 2.11.3 to 2.12.0. One which has only bug fixes would go from 2.11.3 to 2.11.4.

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 Build, write a new Build...

perl Build.PL

Clean up any temporary or build files...

./Build realclean

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

perl Build.PL

Run ./Build manifest to update the MANIFEST.

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

For example...

$ ./Build manifest
Added to MANIFEST: t/dump/formats.t

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/perl5i/VERSION.pm
• dist_version in Build.PL
• MANIFEST
• MANIFEST.SKIP (if you needed to update it)
• Changes

Run ./Build disttest and ensure it passes.

In certain circumstances, you may need to install some packages to get this to run properly. If you see the following error, you should install Software::License:

The 'license_creation' feature is not available. Please install missing feature dependencies and try again.

Run ./Build 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.