How To Make A Release
Clone this wiki locally
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.
PAUSE account?Do you have a
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.
PAUSE permissions for perl5i?Do you have
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.
git checkout master to get on the master branch.
git pull origin master to make sure you're up to date.
Increment the version
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
Z is set to 0.
If there are only bug fixes this release, only increment
For example, a release with new features and bug fixes would go from
2.12.0. One which has only bug fixes would go from
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
- 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
- Only log interesting changes
- Find changes using "git log"
- If possible, associate each change with a Github or rt.cpan.org issue. Like
- If possible, attribute each change with the contributor. Like
Get a clean build environment.
To ensure you have a clean build environment and up to date Build, write a new Build...
Clean up any temporary or build files...
realclean includes the Build file, run
perl Build.PL again to get a new Build file to work with.
./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.
$ ./Build manifest Added to MANIFEST: t/dump/formats.t
git diff MANIFEST to make sure nothing weird slipped into the MANIFEST.
If it did, consider updating MANIFEST.SKIP, deleting the MANIFEST and rerunning
Verify your changes with
Congratulations! You've made all the necessary changes. Review them with
git diff. There should only be changes to...
MANIFEST.SKIP(if you needed to update it)
./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
The 'license_creation' feature is not available. Please install missing feature dependencies and try again.
./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.
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.
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.
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.