|Just another Perl shrine|
RFC: Continuous Integration (CI) for your CPAN modules (for free!)by stevieb (Canon)
|on Jan 15, 2016 at 16:31 UTC||Need Help??|
This guide will attempt to explain the basics of using a version control system (specifically GitHub), along with other free online tools to automate your builds and generate test coverage reports automatically on each update to your code.
It'll be a work in progress for some time (very high level overview at this time), so feel free to leave comments for fixes/updates etc. This doc assumes that you already have module code you've written (eg: My::Module). There's a fair amount of detail lacking because I can't remember the exact steps for everything, but over the weekend, I'll re-run the entire process and fill in the large gaps here.
First, head on over to GitHub, and sign up for a free account, and create a repository (eg: my-module).
Now, install git, and clone your newly created (empty) repo to the local machine:git clone https://github.com/username/my-module
From the directory above your actual module code, copy the contents of the module's top level dir into the new empty repo dir:cp -R My-Module/* my-module
Add these files to git, and perform your first check-in:
You now have revision control for every change you make going forward to your module.
Next, head over to Travis-CI, and sign up for an account with your GitHub username. After signed in, 'sync' your account to github, and in your repositories screen, you'll see an on/off toggle for your new repository. Enable it.
Now go to Coveralls and perform the same task you did for Travis.
At this point, everything should be enabled and ready for use. To proceed, you'll need to set up a .travis.yml file in your distribution's root directory. Here's one that I use in all of my modules. It's configured to run the build on perl versions 5.8 through 5.22, and it'll also perform test coverage in prep for sending to Coveralls.
Note that Travis doesn't do testing on Windows, so I always advise having a Windows machine/VM handy, and run your test suite on there to ensure it runs cross-platform (if necessary) before upload to CPAN.
Perform a change in your code, then commit and push it to GitHub. Now go to your Travis page (mine's https://travis-ci.org/stevieb9/ for example), and your build should be running or just about to start.
If all builds succeed, head on over to your Coveralls page (eg: https://coveralls.io/github/stevieb9/), and you should see a page with your repos listed, with the coverage details of your unit tests.
Click on the repository, and at the top of the page, click "Badge URLs". Copy the entire text that contains the HTML link. You'll need this, along with a Travis link for your repo to add to your POD documentation.
*Note*: I can't remember where I got my own Travis link from, but yours will be the same as mine, simply replace the name of my repo with yours. See the example below...
Now, in your POD, add a tiny bit of markup and paste in your new links. I put mine in the NAME section so it's visible immediately to visitors to my modules on CPAN:
This will result in two images in the NAME section of your POD when users view your module on CPAN. One will show the build success or fail, the other the percentage of test coverage you have.
Here's an example of what this looks like. You can click through both images and get to the full details of both the build process, and the coverage results.