Contributing to My Free Software Projects

This is a quick summary of how I work on my software and how you can contribute.

1. Development Principles
2. Bug Reports [Security Issues]
3. Patches
4. Coding Style [Perl-Specific Coding Style Considerations]

Development Principles

I try to use test-driven development as much as possible; especially for library-type code because it has good testing frameworks; less so for interface code because it can be hard to write good tests.

In brief:

1. If you want to develop a new feature, write an automated test that will test the feature first.
2. Run the test to verify that the software currently fails the test.
3. Implement the new feature.
4. Run the test to verify that the software now passes the test.
5. Keep the test as part of the software’s test suite to verify that any future changes to the software don’t break the feature.

Knowing that may help you understand why I like bug reports and patches the way I do.

Bug Reports

For my Perl projects, the tracker to submit bug reports to is rt.cpan.org. For most other projects, there is probably a GitHub issue tracker. Otherwise, just email me the bug report.

When submitting bug reports, a details example that allows me to reproduce the error is appreciated, and is often vital to actually getting the issue solved. If I’m unable to reproduce the issue, there’s probably little I can do to solve it.

For Perl, a Test::More-based test is the absolute best way to demonstrate an issue. For example, say I have published a function triple() which triples a number, but you discover it actually doubles numbers, send me a script like this:

=pod↵
↵
=head1·PURPOSE↵
↵
Double-check·that·the·C<triple>·function·really·works!↵
↵
=head1·AUTHOR↵
↵
Your·Name·E<lt>youremail@example.orgE<gt>.↵
↵
=cut↵
↵
use·strict;↵
use·warnings;↵
use·Test::More;↵
↵
use·Tobys::Module·'triple';↵
↵
is(·triple(·0·),·····0,·'Triple·0·==·0'·····);↵
is(·triple(·2·),·····6,·'Triple·2·==·6'·····);↵
is(·triple(·100·),·300,·'Triple·100·==·300'·);↵
↵
done_testing;↵

Security Issues

If you find a bug which could cause a security issue and are concerned that the information in your bug report might expose how the bug could be exploited by attacked, then please do still file a bug report on the issue tracker, keep it vague, and email me with the full details.

Patches

If you have written a fix for a bug or implemented a good new feature, then please let me know.

For most of my projects, the pull request feature on GitHub is open, and that is the preferred method to submit patches. If you can’t use git, or are otherwise unable to submit a patch that way, just email me.

Patches following my coding style and including test cases are most likely to be accepted.

Coding Style

For documentation and naming functions/variables, I prefer British English (Oxford English Dictionary spellings).

I indent with real tabs, and use Unix line endings. (I personally set my tabs as three spaces, but the good thing about tabs is you can use your preferred tab size, and I can use my preferred tab size, and it will Just Work™.) Generally speaking, if there are blank lines between chunks of code, I will usually indent the blank lines too. If they’re left entirely blank with no indentation, that’s okay too — I’m not fussy — but if they have some whitespace on them, it should match the indentation of the surrounding code.

For languages with a C-like syntax (C, C++, Java, Perl, PHP, Javascript, etc): operators, parentheses, brackets, braces, keywords, variables, and terms should typically have a space both before them (unless they’re at the start of a line) and after them (unless they’re at the end of a line). This is roughly the same as the WordPress Coding Standards for PHP. I don’t cuddle else.

if·(·condition·)·{↵
⇥  action0(·1,·"foo"·);↵
}↵
↵
if·(·condition·)·{↵
⇥  action1(·3,·[·4,·5,·6·]·);↵
}↵
elseif·(·condition2·)·{↵
⇥  action2a(·7·);↵
⇥  action2b(·8.9·);↵
}↵
↵
foreach·(·$items·as·$item·)·{↵
⇥  process_item(·$item·);↵
}↵

Overall if there’s a conflict between being consistent with coding style, and making a particular piece of code readable, I prefer to make the code readable.

Perl-Specific Coding Style Considerations

Here’s a Perl::Tidy script that roughly enforces my formatting preferences.

I put pod at the end of modules and scripts, not scattered throughout. For test scripts (*.t), I put pod at the start instead.

Always use strict and use warnings in modules, scripts, and test cases. It is fine to disable strict refs or certain warnings in small scopes.

In terms of backwards compatibility, I usually aim to write code that runs on Perl versions as old as Perl 5.8.9. For some, I aim to support Perl 5.6.1.