Contributing to a Free Software Project

A while back I made a small contribution to GitLab and they were so appreciative that they sent me a free mug which I then tweeted about.

This tweet was rather popular, as it was re-tweeted by a bunch of GitLab contributors and staff, and among a few thank-yous, I received one private message from someone asking about how easy it was to contribute and if I had any tips about the process.

As I've done this a few times (mostly as one-offs) and have a few ¹ ² ³ ⁴ Free software projects out there myself, it turns out I did have some pointers. I thought it was worth sharing them here.

1. Respect the requests of the project. If they have a coding style, follow it as carefully as you can. They may come back with requests for changes to conform to the style guide. Just roll with it and adjust your code. For large projects especially it's important that all contributed code conform so that the total project doesn't end up looking like a Frankenstein of different styles.
2. Don't go big (at first anyway). Make your first merge request a small one that fixes a simple thing and/or adds a simple feature. If your changes introduce new functionality, make sure that your merge request includes a test or two to support it. If you don't include a test, it's very common for the maintainer(s) to request one as tests (a) help others understand what your changes are supposed to do, and (b) ensures that other people's changes don't accidentally break your stuff down the road.
3. Be accommodating. This overlaps a bit with 1 and 2, but basically the thing to remember that while you think of your addition as a gift (and it is), it's also a burden to the maintainers. While your code may fix a bug or add something awesome, if it's hard to maintain/understand, doesn't come with tests, doesn't conform to the established style, or some-other-thing-that's-important-to-the-maintainer(s) then you're introducing pain rather than offering something valuable. In a well-maintained project (like GitLab) the maintainers will be friendly and responsive and work with you to get your merge request into a shape that's compatible with the long-term goals of the project. Work with them to do what's needed. Making your first merge request is just the first step toward actually getting your changes merged.

As for the technical part, this is a pretty good process for any merge request to any project (though admittedly I didn't follow this for this one merge request to GitLab as it was just a documentation fix):

1. Check out the code locally and get it running. Depending on the size of the project, you may not be able to get all of it up, but at least get the part you want to change/test.
2. Run the tests and make sure they pass.
3. Create a separate branch off of master (or whatever branch the project asks you branch from)
4. Make your changes.
5. Add some tests to confirm your changes (you may want to do #4 before this one).
6. Run all the tests together to make sure they still pass.
7. Commit everything. Some projects ask that you break up everything into logical commits, while others ask you collapse everything into a single commit. Check the rules for each project to see they have such a policy. If not, use your best judgement.
8. Make your merge request!