If you hang around Github you might have seen a lot of projects adding extra information to their README files in the form of badges, like so:
Not only do they make your project's Github page look cooler, they also help developers, from curious potential users to regular contributors, easily spot how active and healthy is the code.
Wanna join in on the fun? There are several free code badges out there for you to use, and these are the ones (that I know of) that work for your awesome Perl code! \o/
Travis CI
Travis CI is a continuous integration service used to build and test projects hosted on Github. They'll let you know whether your code builds and tests pass in many different versions of perl (but, unlike CPAN Testers, they'll do it in only one platform). Using their service is super simple:
1. Go to the
Travis CI homepage and sign in with your Github account. It's the big link in the top right corner of the page, you can't miss it :)
2. If this is your first rodeo, you'll see Travis CI asks for some permissions on Github. You must allow it to proceed. They have outlined the
whys and hows if you're feeling cautious.
3. Go to your
Travis CI profile page and wait for all your repositories to sync. Once they're all listed in there, it should look something like this (with, of course, your own name, groups and projects):
4. See that "on-off" switch next to each of your repositories? Just flick the ones you want to have a Travis CI report. We're almost done!
5. Add a file named
.travis.yml to the root of your project repository (note the "." in front of the filename!). It should contain valid YAML with the main language and the different versions of Perl 5 you want to test against. For example, if you want to test against 5.14 and 5.20, your ".travis.yml" should look like this:
language: perl
perl:
- "5.14"
- "5.20"
If you need any extra information or customization of your perl builds, just read
Travis CI's Perl specific documentation. Note that if something goes wrong (e.g. you make a typo in the filename or its contents), Travis will assume you're testing against the current stable version of Ruby, which is definitely not what you want :)
A few moments after you commit it to your repository and push it to Github, go back to your Travis CI profile page and you should be able to see the build results! If you skipped a step and added the ".travis.yml" file to your repo
before enabling the project in the Travis CI page, just push any commit to trigger it.
6. Badge time! Make sure your README file is in Markdown - just rename it to README.md and
adjust it as you see fit (it's also a great way to make your project stand out while still making it readable as plain text). Then go to your Travis CI profile and click on the project you want to add the badge. You should see the badge right next to the project's name. Click on it and it's going to let you copy the badge for your project in several formats:
Choose "Markdown" and paste it on your README.md file. The one from Clone, as you can see from the picture above, looks like this:
[](https://travis-ci.org/garu/Clone)
After pushing your changes, go to your project's Github page and see the badge in all its glory!
Coveralls
Now that we have Travis CI doing some tests for us, how about we get some test coverage reports also? That's where coveralls.io comes in!
1 & 2. Just like we did with Travis CI, go to the
Coveralls home page and sign in with Github, granting them access to your repositories.
3. The
Coveralls repository page will list all projects being analyzed for coverage, and now is probably the time to click the "
add repos" button on that page and add the ones you want coverage analysis of.
4. Adjust your
.travis.yml file to add code coverage. Coveralls is engine agnostic so we'll use the not nearly enough praised
Devel::Cover suite to do the hard work, together with the
Devel::Cover::Report::Coveralls interface. Basically, Travis CI gives us a lot of granularity while building and testing our projects, so we tweak it to include coverage commands in the appropriate build steps.
There are a few ways to go about it: in the manual way we export the environment variables we need and install the coverage dependencies. For instance, we could update our file above to look something like this:
language: perl
perl:
- "5.14"
- "5.20"
install:
- export RELEASE_TESTING=1 AUTOMATED_TESTING=1 AUTHOR_TESTING=1 HARNESS_OPTIONS=c HARNESS_TIMER=1
- cpanm --quiet --notest Devel::Cover::Report::Coveralls
- cpanm --quiet --notest --installdeps .
script:
- PERL5OPT=-MDevel::Cover=-coverage,statement,branch,condition,path,subroutine prove -lrsv t
- cover
after_success:
- cover -report coveralls
in the automatic way, we delegate most of the work to some fine-tuned helper scripts created just for Perl projects on Travis and Coveralls. The same original .travis.yml file would, in this case, look like this:
language: perl
perl:
- "5.14"
- "5.20"
matrix:
include:
- perl: 5.20
env: COVERAGE=1
before_install:
- eval $(curl https://travis-perl.github.io/init) --auto
To me this one looks much easier to read, as most of the complexity is enclosed in the "init" script of the
well maintained travis-perl project. I highly recommend it. In fact, after you get it right for your code, I suggest you
go read their helper intro and play with some settings, you won't regret it. Also, check out
Moo's .travis.yml file for a glimpse of all the cool stuff you can get, from testing against blead perl to reporting on a specific irc channel!
5. Now that your commits are tested on Travis CI and reported by Coveralls (mind you, it might take several minutes for a build coverage to show up, and they only start after you push to Github *after* having activated Coveralls and pushed your .travis.yml file), let's put a badge on your README!
On the project listings on Coveralls, click on the project to go to its page, and you should see a badge right at the top, with a "BADGE URLS" link next to it. Click on that link to copy your badge in several different formats, like so:
Put the markdown code on your README.md file next to the Travis CI badge (or wherever you see fit) and that's it!
Version badge
This one really comes in handy for Github, as it lets your users know
exactly what's the current stable version on CPAN and how to get it, and it's also by far the easiest to set up: just go to the
Version Badge link for Perl projects and type in the name of your target dist (note that it's The-Distribution-Name, not The::MainModule::Name). Once you click on "Find", it's going to give you the badge in several different formats ready for use:
Showing your badges on MetaCPAN
Now that your README.md is all shiny and colorful with badges, your project's Github page is starting to look even cooler than the MetaCPAN page, and that's just not cool. MetaCPAN's web interface is awesome and it will look even better when you put your brand new badges in it, so let's get on with that.
Perl's Pod format allows us to to specify sections that will only show when a given format is supported. For instance, if you write this in your pod:
=for html
<img src="http://example.com/path/to/some/image.png" />
Then this block will render the image when the renderer supports html (like the MetaCPAN web interface), and not do anything on renderers that don't support it (like your command line "perldoc"). Pretty cool, right?
Graphic modules and
tutorial-like documentation have been taking advantage of this feature for years, and we should too!
So go to the links above and find the HTML version of the badges, then put them in a "=for html" paragraph at the top of your Pod. For the Clone module they look like this:
=head1 NAME
Clone - recursively copy Perl datatypes
=for html
<a href="https://travis-ci.org/garu/Clone"><img alt="Build Status" src="https://travis-ci.org/garu/Clone.png?branch=master" /></a>
<a href="https://coveralls.io/r/garu/Clone?branch=master"><img alt="Coverage Status" src="https://coveralls.io/repos/garu/Clone/badge.png?branch=master" /></a>
<a href="https://metacpan.org/pod/Clone"><img alt="CPAN version" src="https://badge.fury.io/pl/Clone.svg" /></a>
=head1 SYNOPSIS
...
As soon as you push the new version to CPAN, you'll see the badges right there on MetaCPAN!
If you are too lazy to go back and copy the HTML version from all those sites, just run the following one-liner on your README.md to print the html version of the markdown links in there:
perl -nE 'BEGIN{ say q(=for html) } say qq(<a href="https://www.blogger.com/$3"><img alt="$1" src="$2" /></a>) if /\[!\[([^\]]+)\]\(([^\)]+)\)\]\(([^\)]+)\)/' README.md
Then copy the block to your pod and make a new CPAN release :)
That's all there is to it. Have fun with your badges! \o/
(oh, and let me know if you find any other Perl-related badges you know of)
