4 lessons from my first open source contribution

Welcome new developers and make it easy for new contributors to get started in your project.

I’ve been involved in open source projects for a long time, but I still remember my first contributions in open source. As an undergraduate student in the early 1990s, I interned at a software company one summer. The developers used a “Big Iron” Unix system called Apollo DomainOS that I’d never used before, and the built-in editor was unfamiliar to me. Rather than spend “internship” time learning how to be productive in their editor, I asked if I could compile my favorite editor, GNU Emacs. The project lead said “Yes.”

I downloaded the source code to GNU Emacs, and tried to install it. Unfortunately, the build failed on one line. I don’t remember the exact error, but I was able to fix it pretty quickly. Within the hour, I had a working version of GNU Emacs on Apollo DomainOS.

I thought the GNU Emacs folks would appreciate knowing that I’d fixed the build for that platform, so I created a patch, wrote some notes, and sent them to the GNU Emacs maintainer. I received a very nice reply a few days later, to say “Thanks” for the patch. He let me know that GNU Emacs used to compile on DomainOS, but no one had used it in a while, and later versions drifted away from the working configuration. So he was very glad to have a patch that made GNU Emacs work again on Apollo.

That was an excellent first contribution to open source software, and the interaction went exactly as we’d hope it would: a new contributor submitted a patch, the maintainer checked it out and saw that it worked, accepted the fix into the project, and thanked the developer.

Because of that positive first interaction, I became more interested in open source software. Not long after that, I experimented with this new thing called “Linux” which was a great way to run a Unix-like operating system on my home computer.

A negative experience

A year or two later, I got my first job as a systems administrator, and I installed open source software on the systems I supported. I also wrote small utility programs to make my work easier, but the HP-UX system we ran didn’t have a full C compiler – just some minimal C compiler that HP used to deliver patches.

I searched and found a more modern C compiler that specifically targeted HP-UX, and could be built using the minimal default compiler. But our HP system was the most recent system, and the open source C compiler didn’t fully support the latest version of HP-UX. I did some debugging and found that if I modified a few lines in the open source compiler, I could build a working version that passed the tests. Success!

I created a patch, similar to how I created my patch for GNU Emacs, and wrote up some notes for what I did to get it working, then emailed the developers with my fix.

Where my first open source contribution was welcoming and an overall positive experience, this interaction was the opposite. The maintainer replied to criticize my patch. Apparently I didn’t package the patch the way he wanted it, and he wrote a long screed about how important it was to match the developer’s preferences so it would be easier for him to accept the patch. My fix was three lines long, but it sparked outrage from the developer.

Four lessons learned

If my interaction with the C compiler had been my first open source experience, I would not have continued contributing to open source projects. The developer was very negative, and pushed back on any contributions to his project. Based on that interaction, I stopped using their compiler and just “made do” with what I had. I decided I preferred working with the limited C compiler that came with HP-UX than use a more feature-rich, open source compiler.

Fortunately, my first experience was very pleasant. And based on that positive first exposure to open source software, I became more engaged in open source and contributed to many more projects.

These two “first experiences” provide some great lessons for other open source software projects:

1. Make it easy for developers to reach the right person. If your project has a preferred pipeline to submit patches, advertise that pipeline, including how contributors should package their fixes or navigate a pull request.
2. Provide good documentation about your project, including the history of the project, future goals, and why it makes certain design assumptions. This information is invaluable to first-time contributors. Understanding how and why the project started, and what it aims to do, can help focus new contributions to the right areas.
3. Guide new contributors to ask questions in the right forum. Where should developers ask questions or discuss the project? For very small open source projects, you might have a single “contact” person or “lead” developer who can respond to new contributors. Larger projects may prefer new developers to join an email list or online forum to ask questions. Very large projects might have an “outreach” team that can guide new contributors to make their first contribution.
4. Make the first contribution a positive one. When someone asks a question or submits a patch, consider that this might be their first contribution to any open source project. Make that a positive experience. For example, if someone asks a question that seems obvious to others on the project, don’t reply with anything that sounds like “That’s a dumb question.” Instead, answer the question and suggest an online guide they might read to answer similar questions.