Sending Me Patches

I publish a number of pieces of free software on this web site, and solicit contributions from any who's interested in modifying them. This page includes some guidelines for contributors that will make my life easier and therefore make me more likely to pay attention to their mail.

Send patches

Usually you should send a diff (also known as a patch) between my code and yours, rather than sending a complete copy of the modified code. This has the following advantages:

Exception: if you have your own bzr branch of whatever is, the URL of that is likely to suffice instead (and make much of the advice below irrelevant, though avoiding gratuitous changes and using the latest version remain good).

Use "diff -u" format

The default output from diff is almost unreadable, and although "diff -C" is better it's still very inconvenient. Please only use "diff -u". If you don't have GNU diff, install it (it's not particularly hard).

Include new files

If you add new files then make sure they are included in the diff. This usually requires the -N option. If for some reason it's inconvenient to do this, make sure that you get the new file(s) to me some other way (preferrably in the same email).

Exclude generated files

In many bits of software some of the files are automatically generated (for instance Makefile.in, Makefile, configure). Don't send any changes to such files. The -x and -X options help with this.

Get the order right

The correct order for the command is "diff old new", not "diff new old". patch can sometimes guess what you meant anyway, but the diff is still confusing for a human to read.

Avoid gratuitous changes

Changing the use of whitespace, re-indenting code, and so on, clutter a diff without actually bringing about any change in the behaviour of the code. Usually you shouldn't do it.

Changing variable names, adjusting idiom rather than effect, and so on, might be more appropriate (for instance to make an obscure piece of code clearer) but it's better to separate such cosmetic changes out into a separate diff.

Use the latest version

Make sure you're working with the latest version of whatever it is. If there are separate development and release versions, anything that adds new features should use the development version; only bug-fixes are acceptable for the release version.

Use plain text

Please use plain text in your email, rather than HTML, Word format, or other such inconveniences. But, feel free to include the patch as an attachment; I can cope with MIME including base64 and quote-unprintable. uuencode and direct inclusion are also acceptable, provided that the patch isn't mangled.

I've not formed an opinion on whether large patches should be compressed or not. Small ones definitely shouldn't, and if you do compress, please use only gzip. If I come to a firmer view I'll mention it here.

RJK | Contents