Open Up Your Open Source Module – Part 1: CONTRIBUTING File

You’ve written something awesome! You want to release it as open source software into the world.  And, you hope other people will want to polish the rough edges, oil the squeaking hinge, and translate the help text into Klingon. Assuming that your module is interesting to people, how do you help them help you? I’ll give examples of how to do this in the context of Perl 5 modules, but they’ll work in other languages, too.

I talked about this in a lightning talk @ The Perl Conference 2018

But I also thought I could expand and organize my thoughts a bit better, so for the textually inclined, read on!

This is part one of a five part series.  I’ll link them all here when they are up.

• Part 1 (Below): CONTRIBUTING File
• Part 2: TODO File
• Part 3: CODE_OF_CONDUCT File
• Part 4: Contributor Credit
• Part 5 (Future): BONUS TIPS!

These are my opinions. There are smarter people than Joelle, so feel free to comment if you have a better way to do these things, or if you want to politely disagree.  If you’re idiologically opposed to my suggestions, please don’t think I’m telling you what to do with your own projects – you are, of course, entitled to ignore any and all of my suggestions.  I hope that I can explain well what I do and why, but another developer might have a different (and possibly better) way of doing it. That’s fine! Your language or project may also have different conventions – it’s always best to do as the locals do when those differ from my suggestions.

CONTRIBUTING File

Add a file talking about how to contribute.  If you are writing a Perl 5 module, metacpan.org (the new, spiffy CPAN search engine) will link to this file, if you name it properly in your distribution.  This is one idea I’d like to see other languages steal!  It looks like this (example from the distribution info page on metacpan for one of my modules, Parallel::WorkUnit):

When you click on the “How to Contribute” link, metacpan automatically opens the file and displays it.

How do you get metacpan to do this?  Or what do you do if you aren’t writing a Perl 5 module?  The answer is the same! You want to create a file that has one of the following names, that includes instructions on how to contribute:

• CONTRIBUTING
• CONTRIBUTING.md
• Contributing
• HACKING
• HACKING.md
• Hacking
• Hacking.md

Metacpan will recognize the first file it finds from the above list as the “How to Contribute” file.  Most programmers and sysadmins exploring the distribution will also recognize these as a “how to” document for contributing to your module.

I typically recommend making things as easy on people – including people who might not know the history of a word like “hacking” – to figure out how to contribute, so I name mine CONTRIBUTING, and  I don’t use Markdown, but of course the choice is yours.  This file goes in your distro’s source tarball, in the root directory.

The files ending in .md are Markdown files and have some special syntax that Markdown-aware editors can use to format your Contributing documentation nicely, but still have basically a readable file in a standard text editor that is not Markdown aware.

CONTRIBUTING Contents

So, now, what do you put in the CONTRIBUTING file?  Whatever makes sense for your project!

You can see one of my CONTRIBUTING files here.  Mine isn’t as complete as I would like, but it’s enough to hopefully help a new developer.  I break the file into two main sections – a section that explains how to help the project and another section that gives broad examples of what to do.

In the first section, I like to include a few things – these are the general rules for interacting with the code and me, and would be tailored to fit your workflow:

• What I don’t want you to do!  In most cases, I really don’t want existing modules to get changes that break the existing public interface. I don’t want someone else’s previously working code, that depended upon my module, to suddenly quit working because they updated their installation of my module. So I tell potential contributors that.
• I try to give an indication of how open I am to drive-by changes.  I’m very open to them, but I’d still like anyone wanting to make big changes to chat with me first, to make sure we don’t step on each other or that I might have ideas about how it should be done.
• If I don’t want new features, or if it has been deprecated, I tell people that.
• I give information on how to report bugs on the distro.  We’ll talk more about this later.  If you have a special procedure for security bugs, it’s good to list those too.
• How will I accept patches/changes?  I typically like to get them via Pull Request on Github, so I mention that, but I’ll deal with however you send them to me. People with more commonly modified modules might want to restrict that.
• I tell them what they’ll get out of it. In the case of my modules, that’s typically a mention as a contributor.

In the second section, I provide broad ideas of help I could use. I’ll get into a detailed TODO file in Part 2 of this series, but this differs in that it talks about categories of things I can use help with.  Some stuff I put there:

• I point to the TODO file for concrete tasks people can do.  The TODO file is more of a place for me to list things I want to see happen in the module, so it’s only a subset of what might be desired in the module by the community – a starting point, not an end point.
• I let people know I’d love tests for things that are broken – there are often cases a module has problems with, and they are known and (hopefully) documented limitations I hope to resolve sometime. If someone wants to write tests for those and configure them so that they are “todo” tests (meaning that failure is expected), it gives me an easier starting fix the module code.
• Who doesn’t want documentation patches/fixes?! I explictly suggest that!
• I personally love getting requests for functionality even if the person can’t implement it. I may or may not implement the requested functionality, but it never hurts to ask me.  Others may feel differently, but I let the user know that they are welcome to say, “It would be wonderful if…”  Likewise, if the module doesn’t make sense for some reason, I want people to let me know so I can fix the program and/or docs.
• Stuff like this file and other “meta” stuff — things that don’t directly impact my code, but maybe use the ecosystem better is awesome. Even people who might not know anything about the thing my module does might be able to say, “Hey, you want a CONTRIBUTING file in your distro!”  I want to hear about that.

Again, this is what I do and how I work on not-super-popular modules that I write.  If I was maintaining Firefox or a major Javascript library, I would probably be somewhat more restrictive in how people communicate. But this is the place to list the things people can do that would make your life easier! It’s also the place to try to welcome new contributors.

Stay tuned for Part 2 – the TODO File!