How to Maintain Open Source Project

A project is maintained with the help of developers, UX designers, and marketing experts. Each member of the team holds responsibility for a certain part of the application development process. The main idea is to develop a framework or platform where users can get the information they need.

This guide is intended to help new project maintainers make the transition from newcomer to experienced maintainer. It’s a collection of the things that I wish I’d known when I first became a project maintainer. Since then, I’ve helped hundreds of new project maintainers and collected their advice, and this guide has evolved over a number of years into what it is today.

Write Useful Documentation

Documentation that is thorough, well-organized, and serves the intended communities of your project will help expand your user base. Over time, your user base will become the contributors to your open-source project.

Since you’ll be thinking through the code you are creating anyway, and may even be jotting down notes, it can be worthwhile to incorporate documentation as part of your development process while it is fresh in your mind. You may even want to consider writing the documentation before the code, following the philosophy of a documentation-driven development approach that documents features first and develops those features after writing out what they will do.

Along with your code, there are a few files of documentation that you’ll want to keep in your top-level directory:

Documentation can come in many forms and can target different audiences. As part of your documentation, and depending on the scope of your work, you may decide to do one or more of the following:

  • general guide to introduce users to the project
  • Tutorials to walk people through different use cases
  • FAQs to address frequently asked questions that users may have
  • Troubleshooting guides to help users resolve problems
  • An API reference provides users with a quick way to find API information
  • Release notes with known bugs to let users know what to expect in each release
  • Planned features to keep track of and explain what is coming up in the future
  • Video walkthroughs to provide users with a multimedia approach to your software

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!

Choose a license

This is easy to overlook. You might think, who cares? My project is small, and I don’t care what people do with my code.

Well, a license doesn’t just protect you or your project.

It gives people confidence in using and/or contributing to your project.

I’ve seen people online say that if your project doesn’t have a license, they won’t contribute to it or use your code in any of their work.

If the rules aren’t clear, why risk getting involved?

Write down your project’s vision

Start by writing down the goals of your project. Add them to your README, or create a separate file called VISION. If there are other artifacts that could help, like a project roadmap, make those public as well.

Having a clear, documented vision keeps you focused and helps you avoid “scope creep” from others’ contributions.

For example, @lord discovered that having a project vision helped him figure out which requests to spend time on. As a new maintainer, he regretted not sticking to his project’s scope when he got his first feature request for Slate.

Helping Others Contribute

Whether or not you expect anyone to contribute to your project, you should be prepared for the possibility of others wanting to help your cause. And when that happens, your contributing guide will show those helpers exactly how they can get involved. This guide, usually in the form of a CONTRIBUTING.md file, should include information on how one should submit a pull request or open an issue for your project and what kinds of help you’re looking for (bug fixes, design direction, feature requests, etc.).

Automate Tasks

You can improve the efficiency and quality of your project by automating maintenance tasks and testing. Automated maintenance and testing can continuously check the accuracy of your code and provide a more formal process for approving contributor submissions. This helps free up time so you can focus on the most important aspects of your project. The best news is that there are plenty of tools that have already been developed and may fulfill the needs of your project.

Keep in mind that less is more. Be intentional about the processes and tasks you choose to automate in ways that can optimize efficiency, production, and quality for your project, yourself, and contributors.

Conclusion

If you are an active participant in an open source project, this post is for you. It explains how to maintain your software throughout the release cycle and by following a few simple steps: it empowers you to help the project maintain its momentum through regular releases and helps you get more hands on experience.

0 Comments

No Comment.