NeilB

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:

=head1 REPOSITORY

L<https://github.com/neilbowers/Foo-Bar>

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.