Put your CPAN distributions on github

If your CPAN distributions aren't already on github, then I think you should consider adding them. Github is the most popular code hosting service, so it's the first place many people will look for your code.

If your distributions are on github, it makes it a lot easier for people to submit changes (like bug fixes) via pull requests. And if it's easier, it's more likely that people will.

If you do add your dists to github, then you should make sure that you give the repo in the dist's metadata and the documentation too.

I'm always happy to hear suggestions for improving these posts, but especially in this case, as I'm a git and github beginner.

Why github?

Lots of CPAN distributions are already on github, which means a lot of people are familiar with using it and contributing via it. If I spot a bug, and think I can fix it, if it's on github I'll send a pull request, otherwise I'll send a bug report.

Adding your distribution to github

Let's say you've already got a module Foo::Bar, which is on CPAN as distribution Foo-Bar (it's got the right name). And now you want to put it on github. There are seven steps:

  • Create a github account, if you haven't got one already.
  • Create a local git repository for your distribution.
  • Create a repository on github.
  • Link your local repository to your github repo.
  • Push your current version to github.
  • Add your github repo to your dist's metadata.
  • Mention the github repo in your dist's documentation.

Now we'll go through those step by step. Sometimes I'll use repo instead of repository, and dist instead of distribution.

Create a github account

Creating a github account is easy: when you go to github.com, you'll get a signup form.

If you're not familiar with git, then github have a collection of online resources for learning git and github.

Create a local repository

Assuming your distribution already exists, here's how to 'import it into git'. Start off by changing to the top-level directory of your distribution:

cd Foo-Bar
git init
git add *
git commit -m "initial import"

Create a repository on github

When you login to github, on your home page you'll see a green button for creating a new repository; clicking on it takes you to the new repo page. Here you need to provide

  • A repository name. You should based this on the CPAN distribution name. I just use the CPAN dist name myself, put some people add a prefix or suffix, so you might go with p5-Foo-Bar or perl5-Foo-Bar, for example.
  • A description. This should be based on your module's abstract, but where the abstract shouldn't include mention of "for Perl 5", the github description should (at the end of the description, for example).

Leave the repo as public -- you want other people to be able to find it, fork it, and send you pull requests after all.

Click on the Create repository button. You'll get a page which has some hints on how to get using your repo. You'll notice that some of those hints appear in this article. That's no coincidence :-)

Link your local repository to your github repo

Git is a distributed revision control system, which basically means that copies of your repo can end up all over the bloody place. Now you need to connect your local repository to the github one, and in doing so mark your github repo as the 'master copy':

git remote add origin https://github.com/neilbowers/Foo-Bar.git

This path appears in the response page after you create the repo (my github username is neilbowers).

Now your local and github repositories are linked together, but there's still nothing in your github repo.

Push your dist to github

Assuming your local copy of the distribution is the most recent release that's on CPAN, now you want to push it to github, so that the github repo mirrors what's on CPAN.

git push -u origin master

If you got and look at the repository on github, you should now see your files.

Add your github repo to your dist's metadata

Next you need to add the repo to your distribution's metadata. This lets tools find the dist's repo — it will appear on the sidebar in MetaCPAN, for example. Gabor has written a tutorial on how to link your dist's metadata to github.

Add your github repo to your dist's documentation

The final step is to record your dist's github repo in the dist itself. Add a section in the pod, near the SEE ALSO, and remember to make it a link:



Note that this is the URL to the repo's web page, i.e. without the .git file extension.

The development and release cycle

This sections shows how git and github might fit into your development and release cycle for your CPAN distributions.

Here's how you might make this change, and release your dist. First you edit Makefile.PL, to make the changes as per Gabor's tutorial. Then edit your module to bump $VERSION and add the repo, and then edit Changes, to add a section for the release you're about to make, and add bullets describing the changes:

vi Makefile.PL
vi lib/Foo/Bar.pm
vi Changes

Test that your changes haven't broken anything:

perl Makefile.PL
make test

Release to CPAN; let's say this is version 0.06:

make dist
cpan-upload Foo-Bar-0.06.tar.gz

Commit the changes you just made:

git commit Makefile.PL lib/Foo/Bar.pm Changes -m "added github repo"

Then you should tag the release. The convention is to use the version number, with a leading 'v':

git tag v0.06

And finally you need to push this latest version to github:

git push --tags -u origin master

Note that if you use Dist::Zilla, there's a lot less typing, as you can configure all of the above to be done for you. Read the documentation to find out more. The Dist::Zilla::Plugin's to look at: GithubMeta, Git::Contributors, Git::Check, Git::Commit, Git::Tag, Git::Push.

Thanks to KENTNL, ETHER, and BOOK for commenting on drafts of this.


Great! Would be a good tie-in to see a migration post for people still using CVS on SourceForge ;)

Wasn't there a project to import all the CPAN distributions into github? If that's still running, seems that it wouldn't be a huge extra step to add links to those repos in metacpan. This would at least provide a fallback for cases where no VCS repo is provided in metadata.

Also, if lack of a github link is putting people off from contributing to some modules, how about a gitcpan script which generates a local repo from the latest release, and a wrapper for raising a "pull request" via RT?

I'd expect there to be a lot of modules on CPAN that'll never have VCS repo information added (for various reasons). Perl may be of use in providing appropriate wrappers and helpers to ease any pain in making dev submissions =)

If these things exist, perhaps they need more publicity? I'd be mildly surprised if there weren't a dozen scripts and modules out there already which do all this and more...

Neil, actually I have migrated a lot of repos from cvs to git... I wasn't asking for an answer. But I liked your post which has perl specific flavor to it. So I thought it would be nice to have a migration post for Perl maintainers.

For example, markdown files weren't in use until relatively recently. Although github users are familiar, Perl maintainers not on github may not.

Also it would be nice to understand the assertion/promotion of using github instead of a solution like bitbucket.

Anyways, it was just a suggestion for what I thought would be a nice tie-in to this post.

I use BitBucket for my private projects and most of my cpan modules are there as well. I'm 100% in agreement with moving active cpan projects to public git repositories, but is there a compelling reason why they should all move to github?

As a related aside I don't like RTCPAN. Even though I've started specifying an alternate bugtracker in my recent releases, tickets still get submitted through rtcpan. The makers of BitBucket provide the (high end) JIRA ticketing system to apache httpd. Both BitBucket and GitHub provide a more basic ticketing system for each project for free as well.

A nice (and key) feature of Git is that you can easily add any number of upstream's which you you can push too at will.

So whilst you may prefer to use your own private git repo, or another git service (http://repo.or.cz/ for example) - you can easily push releases to Github. Perhaps you could automate it with Dist::Zilla or one of its friends so you dont even have to think about it.

The advantage is that Github really has "critical mass" which maximizes your chances that someone will send you a patch or bug fix as a pull request.

The aforementioned multi-upstream features, allows you to quickly pull those changes - vet them as you see fit, then push them to your preferred repo location.

So it becomes not a discussion about if you as an author love/hate/dontcare about Github - its merely that by having your code on Github you make it convenient for more people to work for free on your software :)

Nice, but that gitpan link brings out a Pink Unicorn.

Thank you for posting these clear directions. Github does offer advantages, but getting started with it is not always obvious. I know I've had to struggle a lot, and clear directions, including the workflow, will be a big help for a lot of people.

Most of the arguments for using GitHub apply equally to any other good hosted git based service. The advantage GitHub has over its competitors is that it is the most popular, and most CPAN authors already have accounts there.

Before I move my modules to github, I would like to hear what the people who operate the CPANTesters and CPAN and manage its software, and the two indexing sites think.

Also, don't forget to add a link to your Github account from your MetaCPAN profile. This will help potential contributors to find your repositories even if you forgot to put the link in META.yml/json.

Leave a comment

About Neil Bowers

user-pic Perl hacker since 1992.