NEILB's Blog

I sometimes ponder on how we can encourage people to become more active in the Perl communities. Following feedback from participants in the Pull Request Challenge, it's clear we could make many of our CPAN distributions more contribution-friendly. A recent blog post and some discussion with Sawyer prompted some specific ideas.

Highlight easy bugs and feature ideas

If you use github issues for your dists, you could add tags to identify which of them are suitable for beginners. If there are some simple housekeeping tasks you been meaning to get to, you could add those, appropriately tagged.

Add hints to your open issues

Bug reports are often quite terse, and can assume a lot of knowledge. You could add comments, explaining where necessary, and outlining how you'd go about fixing them. You don't have to go into excruciating detail, and ending with "shout if you need more detail or some help" may nudge someone to try.

Open issues for CPAN Testers fails

If one of your distributions has CPAN Testers fails on an operating system you don't have access to, you could open an issue and tag it with the operating system and "help wanted". Maybe someone who has have access to the OS might be prompted to help you.

Close old issues

There's nothing more annoying than starting to dig into a bug, and then eventually realising that it's been fixed in a previous release, but the bug wasn't closed.

Have a github repository

Have a github repository for your distribution, and add a link to it in the distribution's metadata. One very obvious benefit of doing this is that the repository will appear in the left sidebar on MetaCPAN when someone looks at your distribution.

I've found that I'm much more likely to submit a quick fix if there's both (a) a github repo, and (b) it's linked off MetaCPAN.

Keep the github repo in sync with CPAN

Every time you do a release to CPAN, please remember to tag the repo with the CPAN release and then push it to github, so that github is always in sync with CPAN. The convention is that if you release 0.05 then the tag should be 'v0.05'.

If you use Dist::Zilla, then you just need to add the following to your dist.ini:

[Git::Tag]
tag_message=
[Git::Push]

Let people know how to get in touch

Make yourself contactable, whether by telling people where and when they might find you on IRC, your preferred email address, or just via comments on github issues.

Have a CONTRIBUTING file

In the top directory of your distribution, add a file called CONTRIBUTING or CONTRIBUTING.md. For a small dist, this could just be a few bullets on how you would like people to contribute:

• I prefer to get pull requests rather than patches. Please do pull requests on branches.
• Please add an entry for each change in Changes as well.
• If it's a significant change, please email me first, so we can discuss it, and I can tag it as being worked on.

For larger projects these can be quite large documents; eg Moose::Manual::Contributing.

Recognition of contributors

Appropriate recognition of contribution can often encourage people to make more contributions. Acknowledge them in the Changes file, add a Contributors section to the documentation (which can be done automatically), and thank them in tweets and/or blog posts.

What other things might make distributions more welcoming, particularly to beginners?