This is a collection of suggestions for how to increase the likelihood
of a random pull request (PR) being merged. This particularly applies
to the CPAN Pull Request Challenge, where you're
trying to come up with a PR on a randomly assigned CPAN distribution.
These ideas come from feedback I've had from people on the receiving
end of random PRs, and discussions with experienced CPAN authors.
This is based on the assumption that you want your PR to be merged.
If you keep doing PRs and they're never merged, you're going to get
downhearted and eventually give up. And we don't want that.
Plus the idea of the PR Challenge was to get people making useful
contributions to CPAN, to improve CPAN for all of us.
So we want everyone to be making good PRs and for them to be merged.
The What: do something useful
A PR is most likely to be merged if the maintainer thinks it's
useful / valuable. Here's a list of the main types of things you
might consider, in decreasing order of value.
First, here's a list that I think very few authors would disagree with:
Things the maintainer explicitly tells you they want
Improve performance, if you can find hotspots with Devel::NYTProf.
Improve the distribution's kwalitee, as measured by CPANTS.
Profiling code can be tricky. You need to exercise
the module in a realistic range of ways, to ensure you don't optimise for
one use case at the expense of some others.
Or that you don't introduce bugs by rewriting some code for performance,
particularly if the testsuite doesn't provide good coverage.
In addition to the documentation,
have a look at Tim's slides.
Not all authors care about improving their distribution's Kwalitee,
so check with the author first, particularly if that's the only change
you're proposing to make.
The How
Email the maintainer. When you first get your assignment, if there's
no obvious bug for you to work on, email the maintainer to ask if there's
something you can do to help. The earlier in the month you do this,
the longer the maintainer has to reply. Email the maintainer's
CPAN email address. Note: this may bounce.
Raise a github issue. Once you've got an idea for a change, open a new
issue describing what your proposed change is, and why you think
it's useful. Be polite. If the email in the previous point bounced,
the maintainer might still get this notification.
Also, raise a ticket on the RT queue for the dist. If the distribution
has co-maintainers, then they'll get notified. They may have additional
ideas for a useful PR.
Check if there's an IRC channel for the dist, or at least a relevant
one for discussing the dist and asking for ideas or feedback on your idea.
If you're not sure, ask on the #pr-challenge channel on irc.perl.org.
Don't reformat code or change idioms, unless you've explicitly checked
this with the maintainer. Refactoring the code with no good reason could
easily annoy the maintainer.
Make sure that all previously passing tests still pass.
The first thing you do after cloning your fork should be to run
the testsuite. If any tests fail, check CPAN Testers to get the bigger
picture, and you've probably found at least one useful PR you could do.
If there aren't any tests then you've definitely found your first PR!
Add tests for any new behaviour introduced by your PR.
Document your changes.
Don't break the interface.
Build your PR from atomic commits and limit each PR to related commits.
If you want to submit multiple unrelated changes, put each one in
a separate PR.
Write good commit messages. Document the why as well as the what.