Maybe the real treasure was the pull requests we closed along the way!

How to successfully maintain an open source project

Jane Elizabeth
open source
© Shutterstock / 4 PM production

Getting your project up and running is only the beginning. How can developers make sure their hard-coded open source project will succeed? Here are some tips, tricks, and lessons learned for making sure your project is a total success.

You’ve done it! Your personal project is finally on GitHub. Well done, you! But, what comes next? How do you keep your pride and joy up to date and well maintained, so others can enjoy and utilize the open source project you’ve slaved over?

Today, we’re taking a look at several tips and tricks for developers who want to successfully maintain their open source projects. No one wants their hard work to gather metaphorical dust on GitHub. So, let’s dive right in on some of the best ways to keep your open source project freshly maintained and a success!

The basic organizational details

First things first, you need a software license. While no one wants to involve lawyers, if you leave one out of your project, it is implicitly copyrighted. It’s hard to succeed as an open source project if you’re under copyright, you know?

Jeff Atwood has a great roundup about the different kinds of software licenses available. It’s a little out of date, but the point stands. Pick a license, any license, and add it to your project. Preferably, make it very visible on your project’s README file or landing page.

Every license is a little different, so do a bit of background research and make sure it fits with the ethos and vision for your personal project.

SEE ALSO: Feeling generous? Open source software community gives shelter to code

Where are we going with this?

So, put on your thinking cap and figure out some basic details. You need to be explicit and succinct: what is your project’s goal? Its approach? Be clear here. Setting down appropriate guidelines here can save bucket loads of trouble down the line.

Having some kind of organizational philosophy makes it easier for future contributors to go forward in the right direction. Plus, it also makes it easier to say no to requests and contributions that go in a direction you’re not excited about. You can just point to the original philosophy and say, “thanks, but no”.

Your organizational philosophy should be in the README file as well. It doesn’t have to be long; just a few sentences about the goals for the project and what you’re trying to do with it. Contributors shouldn’t have to guess.

This also includes things like a project roadmap or a vision.

SEE ALSO: Know your history — Open Source’s software freedom movement

Contribution guidelines

Speaking of contributions, it’s important to have clear guidelines in place for anyone who wants to contribute. No man is an island and no successful open source project is maintained by just one developer. So, having a clear set of guidelines can definitely help your project succeed.

In the spirit of open source, it’s probably a good idea to look at other popular projects and nick their guidelines. That way, you’re adhering to a common approach and not making it wildly difficult for others to contribute. There’s a great contributing guideline available here.

You should also have a CONTRIBUTORS.txt to track who is helping out.

This covers things like expectations and rules, to keep maintenance a simple process. The Open Source Guide has an excellent section on this, suggesting you include things on:

  • The process for how a contribution is reviewed and accepted. (Do they need tests? An issue template?)
  • What kinds of contributions you’ll accept (Do you only want help with a certain part of your code?)
  • When it’s appropriate to follow up (for example, “You can expect a response from a maintainer within 7 days. If you haven’t heard anything by then, feel free to ping the thread.”)
  • How much time you spend on the project (for example, “We only spend about 5 hours per week on this project”)

SEE ALSO: Is Commons Clause open source? Weighing in on the Redis license change

Good communication skills keep your community happy

Seriously. Open lines of communication help keep things clear. Clarity makes it easier for users and contributors to get the information from the documentation, lowering the number of redundant questions.

Although it can sometimes be irritating if a user asks a question that is clearly covered in the documentation, keep your cool and strive to be helpful. Keep zen and point them in the right direction. Sure, being a little curt is easier, but it’s hard to win friends and influence people if you’re being a dick.

Instead, try to remember that you’re building a community here and that you too started out as a beginner. Be kind, be helpful, and be informative.

This is especially true in cases where you need to say no. As the Open Source Guide points out, “Saying no isn’t fun, but “Your contribution doesn’t match this project’s criteria” feels less personal than “I don’t like your contribution”.

Practice a kind but firm no for suggestions you’re not crazy about in the issues and pull requests, derailed discussions, and requests for more unnecessary work. This is where clear guidelines and rules come in handy!

SEE ALSO: Who should fund open source projects?

Maintaining your maintenance

This project might be your baby. But it’s not your actual baby. Set guidelines for yourself as to how much work you plan doing a week or a month. Be realistic. Unless your actual job lets you work on open source projects in the office, you’re likely doing this in your spare time. You will have other demands on your time, like a partner, family, friends, and pets.

Don’t give burnout a chance to singe your love for this project.  Instead, schedule a nominal number of hours a week or a month to maintenance issues. Hopefully, if you’ve set up clear enough guidelines, you should be able to avoid some of the less important scutwork.

Try to automate wherever you can. The Open Source Guide has a bunch of great ideas on this, including a bot to automate your releases, a bot that mentions potential reviewers for pull requests, and an automated code review.

This also includes things like automated tests, so contributors can make sure they’re not breaking anything when they add on the latest fix. Having all contributions pass an automatic test or two also guarantees a minimum quality for your repo.

SEE ALSO: GitHub invites developers to join Open Source Fridays

In conclusion

After the initial euphoria of publishing a project fades, the reality sets in. Maintaining an open source project often requires a completely different skill set than the initial development. Often, this is a lot of documentation and organizational work. However, this is valuable stuff: badly maintained projects with poor documentation don’t succeed. Or worse, they lead to security breaches and bad news for anyone using them.

Successfully maintaining an open source project boils down to a few simple things: clear goals, well-maintained documentation, and open communication with the users and contributors. Following these general guidelines should help you develop and maintain the project of your dreams.

Good luck, and happy developing!

Jane Elizabeth
Jane Elizabeth is an assistant editor for

Inline Feedbacks
View all comments