10 lessons I learned from maintaining an open source community for 4 years

10 lessons I learned from maintaining an open source community for 4 years

My open source story begins in 2014. I was living in NYC and benefiting heavily from going to free tech meetups like Hacker Hours, where strangers would come together to cowork and help one another out with programming questions. As a recent college grad who didn't have a hugely collaborative learning experience on campus, finding that knowledge sharing culture in the learn-to-code movement at the time was a lot of fun.

The only problem with meetups was that they could be distracting. Instead of finishing the MOOC courses I'd signed up for, I'd get pulled into side conversations about tutorial recommendations and general chatter.

The "running partners for code" idea

That summer, while participating in a program "to launch a side project" taught by Gary Chou from Orbital, I accidentally discovered that the act of screensharing with a study partner on Google Hangouts was a brilliant way to tackle the distraction problem. I found that many beginners easily got stuck in the middle of a coding tutorial, but pairing with other people was an efficient way for them to debug those problems faster. Also, "remote meetups" could happen at any time and place with a reasonable wifi connection. I wagered this would help parents and other people who couldn't easily commute to tech meetups due to scheduling or geographical issues.

Open-sourcing the idea

I set out to try to create a space for the idea of "remote running partners for code." Initially, the Google Hangouts were self-organized in a bunch of Google Group mailing lists, and a small few-hundred-person community grew from it. After a few months, it was apparent that we needed a proper event platform to list and host those remote study sessions. So I started a GitHub repo built on top of MeteorJS for the project.

CodeBuddies is now five years old, and has grown into an international community that is still 100% volunteer and not-for-profit. Open-sourcing it was the best thing I did. Although it is not a "traditional" open source library or tool, many of the learnings and challenges I experienced match exactly what other open source maintainers experienced, as I found out from going to open source summits like SustainOSS in 2017 and 2018.

Below, I share ten lessons I learned from maintaining this open source side project.

Lesson #1: Learn from your contributors

You will learn SO much from your contributors.

I distinctly remember two core contributors (distalx and d3vild06) teaching me two basic lessons very early on in the project:

• Don't let contributors push directly to master. Have them fork the project, and open up pull requests.
• Make sure to review the code in pull requests. Don't blindly accept contributions.

Looking back, I'm a little amazed about how basic those lessons were. But I took the feedback, and continued to learn more lessons from each new person bringing their diversity of  perspectives, questions, and technical knowledge to the project.

Some of the many things I learned from contributors wasn't even software-related, but design, project-workflow or community-related. I learned what was confusing for brand new coders making their first pull request. A contributor (olii) vastly improved an early CONTRIBUTING.MD document I started. I learned how to set up CircleCI, and how to work with design tools like Invision.

Lesson #2: Host live code walkthroughs of your project

I dog-fooded my own project by scheduling hangouts on codebuddies.org/hangouts that centered around walking new contributors through the codebase. I would recommend other open source project maintainers do the same thing, for the following reasons:

• It provides a space for new contributors to ask you questions they normally wouldn't type out
• It really helps people new to git and GitHub. Pairing with someone on their first PR can help them get past the first bumps of setting up the environment, figuring out the codebase, and how to use git.

I've found that conversations can help strengthen connections. More than a few people who've joined code walkthroughs I've done have become major contributors and friends.

Lesson #3: Use GitHub's features to your advantage

Some quick tips I'll share related to using GitHub to your advantage, in list format:

• Take advantage of GitHub's issues and PR templates.
• Protect your `master` branch.
• Use CI integration so that newly submitted PRs are run through checks before you merge them.
• Be deliberate about adding easy-to-search-for labels to your GitHub issues. On CodeBuddies, for example, a contributor (billglover) took it upon himself to clean up the labels and introduced a more efficient system for labeling issues.

Make sure that your contributors are communicating about the issues they're working on, too. For example, during high-traffic times like Hacktoberfest, it can be very easy for multiple people to make PRs for the same issue which ultimately conflict with each other.

At CodeBuddies, this is the policy we settled on to minimize issue conflicts:

• If a contributor finds a bug or has a feature request that hasn't been filed yet as an issue, ask them to file it.
• Ask direct contributors to assign themselves to issues.
• Ask new collaborators to comment on an issue if they intend to work on it.
• A maintainer will re-label the issue from help-wanted to claimed.
• If the person who claimed the issue doesn't report back with updates for a couple of days (or doesn't respond that they still intend to look at the issue after a couple of days), the maintainer will re-mark the issue as help-wanted once more.

Lesson #4: Contributions don't all have to be code

Contributions don't all have to be code. On CodeBuddies, we use the all-contributors plugin, which recognizes alternate contributions that contributors can offer to a project -- like design, help with documentation, project management, content, contributor walkthroughs, pull request reviews, and discussions on Github issues.

CodeBuddies would not be what it is today without adachiu, who designed CodeBuddies' logo and many parts of the site.  

And it might not have a Medium publication or a transparent way of collecting 501c3 donations on our Open Collective if not for distalx, who in addition to being a core code contributor, suggested both services.

I've also generally tried to give contributors the space to add to the project in the ways that they desire -- which have often led to creative additions to the project. For example:

• Buddybot, created by billglover, lets users in the Slack community flag message to a private admins channel.
• Greetbot, created by bethanyg with help from stain88 and angelocordon, sends a welcome message to new members on the Slack and lets users request programming resources from the bot
• Members have interviewed each other in podcast episodes about their coding journeys
• Gaurav coded a Slack integration (blog post) that lets members schedule hangouts on CodeBuddies from within Slack

Ultimately, the community wouldn't be what it is today without the participation of countless people who've given feedback, helped one another with programming questions on our Slack, and hosted hangouts inviting strangers around the world to learn with them.

I remember the first time I attended a study hangout one weekend with random participants -- who, it turns out, were joining from Australia, Nigeria, Finland, Hong Kong, and India. It was incredible -- all of us in different time zones randomly free at the same hour, coming together with a shared intellectual interest in improving our understanding of a technical concept. And it was because someone had planted a time and space by scheduling it on our website. Those contributors help too.

Lesson #5: APIs change!

The dependencies that your open source project rely on might very well change over the course of your project.

I remember distinctly when Google deprecated its Hangouts API in 2017; we had to scramble to find an alternative, and ended up landing on Jitsi.  

Keep an eye on Github Security Alerts, too. These notifications will typically flash at the top of your repository.

Some other tools that can help you stay up to date on security warnings and dependency upgrades:

• Snyk
• Greenkeeper
• Dependabot

Lesson #6: Work in public

Yes, working on open source is by its very nature public -- but there are other ways you can work publicly too. For example, you can:

• write blog posts (Medium and Tumblr)
• write release notes
• make videos interviewing your community members and core contributors
• stream to Twitch as you're working on the codebase
• create an open channel in your Slack or Discord community to invite questions and discuss project updates

All of these activities can help the community better understand your project roadmap, better onboard new contributors, and shine a light on the progress you've collectively made so far.

Lesson #7: Money is not the only reward for thanking your contributors

A big topic at SustainOSS -- an open source sustainability conference I attended in 2017 and 2018 -- is how to get financial support for open source projects. Nadia Erghbal wrote a great guide for this in 2016.

One of the less-talked-about topics is the many ways you can reward contributors if money is not something your project has in abundance.

First, it's important to remember that money isn't something people necessarily expect to be rewarded with when they contribute. Common reasons for contributing include:

• Opportunity to build their technical skills or explore a new technology
• Belief in the mission/overall goal of the project
• Opportunity to work collaboratively with other people
• Opportunity to talk about their work in a future job interview

My main tip for non-monetary rewards is to:

• Thank your contributors in release notes.
• Find sponsors willing to donate non-monetary things like site hosting (thank you DigitalOcean, MongoDB Atlas, and Netlify!), a promo code for a course (thank you egghead.io and Tyler McGinnis!), or swag that you can raffle away to your contributors.

If you do happen to have a small budget because of a small grant reward or donations (like we do on our Open Collective), I don't think you should feel bad about using some of the money to buy stickers -- or to pay your core contributors.

Lesson #8: Your community management and project management skills are valuable too

As an open source project maintainer, you could be wearing multiple hats:

• project manager
• product manager
• engineering manager
• community manager
• grant writer
• code contributor

Open source is essentially strangers working together and crowdsourcing code. As a maintainer, you'll hit conflicts you'll have to mediate such as people disagreeing over a technical direction, people taking sides over a potential Code of Conduct violation, and tone misunderstandings between people who are communicating primarily via text.  

You'll have to make roadmap decisions, communicate a vision, prioritize issues, onboard new contributors, learn to delegate, and hopefully also inspire/support emerging leaders.

To be honest, I did not set out intending to sign up for all this work. It found me naturally over the last few years as the community grew, and as I learned from the ideas and feedback given by members who cared about the project. So in a way, the community gave me the opportunities to learn.  

Lesson #9: It's okay to take breaks

Burn-out is real. Take care of yourself! Especially when maintaining an open source project is not your full-time job.

For side projects in general, the advice I would give is to figure out what you want to get out of it. Are you working on it to learn? Because you believe in the mission? Because you enjoy collaborating with folks who are contributing to the project? Because it's introducing you to technical or leadership skills you wouldn't have the opportunity to practice in other contexts?

Gary Chou once gave me some sage advice: stop working on a project (or take a break) as soon as it stops being fun. This is especially true when you're dealing with any side project that is emotionally draining.

LESSON #10: IT NEVER ENDS

Something that took me a while to accept was that CodeBuddies would never be "finished."

Ultimately, every open source project faces this issue. Abandoned projects can potentially cause disasters. A key question that communities like #sustainnoss is exploring is how to make open source projects more sustainable.

Conclusion

Open source is ultimately a feedback loop between maintainers and the community, where both learn from and give back to each other. Giving back takes many forms; recognition is really important. (And to a lesser extent, so is swag -- as Hacktoberfest is revealing, everybody loves swag. 😂) But prioritization is necessary for a healthy community. Taking care of your own needs as a maintainer is critically important.

Next steps for Codebuddies

This not-for-profit side project is still alive after five years, which is a bit of a miracle. Contributors are currently exploring new technologies to replace the current codebase by prototyping out simple apps using various technologies (Go vs. Node vs. serverless vs. Django). You can follow the progress of these explorations in the release notes here.

If you'd like to contribute or participate, you can still:

• join us at codebuddies.org
• say hello on our Slack community and ask a programming question (or help someone out) in channels like #advice, #javascript or #python
• join or schedule a hangout to study remotely with another independent code learner
• sign up for our newsletter
• follow us on Twitter or YouTube
• sponsor us if you are a company, or donate as an individual to our Open Collective

Linda is a software engineer at Mailchimp. She enjoys learning with people, recording code-inspired violin music, and identifying as a Hufflepuff. You can find her on Twitter or YouTube.