Best practices to manage an open source project

A well-managed open source project attracts contributors and gives them a good experience, making them eager to contribute time and time again. So, if you have an open source project and are wondering what good open source project management looks like, know it’s not a one-and-done activity. 

In today’s article, we’ll show you how to improve your open source project management, assuming that your goal is to attract more contributors. So keep on reading to learn how you can better manage your project and make sure developers have a great experience when contributing to it.

Onboarding new contributors to your open source project

When a possible contributor opens your project page and scrolls down, they need to immediately see a clear README.md file. In that file, it’s helpful to introduce the project as supported by a community so that people don’t mistake open source projects for commercial software.

However, besides the README.md file, you should also consider having CONTRIBUTING.md, ROADMAP.md, and a LICENSE.md files. If you wish, you can combine them all in the README.md, but we suggest having separate files for better information organization.

• README.md – introduces the project, its purpose, and basic installation requirements;
• CONTRIBUTING.md – gives clear instructions on how to contribute to the project;
• ROADMAP.md – shares the vision for the project and the tasks that need to be done;
• LICENSE.md – provides information on the reuse and permissions associated with the code.

These files will allow you to clean several obstacles to open source contribution. Let’s take a closer look at all of them and what information needs to be in each.

README.md file

The README.md file is one of the first and most important things you’ll add to your project repository. This file helps you welcome, orient, and encourage newcomers to contribute to your project. A welcoming and powerful README.md file includes:

• Welcoming note, saying hello to people and welcoming them to the project;
• Presentation of the project, showing what you’re doing, for who, and why;
• Explanation of what makes your project unique and useful;
• Current status of the project, with build information and main contributors;
• Step-by-step instructions on how to get started using the project;
• Basic uses cases and examples on how to use the project;
• Description of the resources and types of contributions you’re looking for;
• Pointers to key resources, like the CONTRIBUTING.md, ROADMAP.md, and LICENSE.md files;
• Contact information (if you like).

💡 Examples of README.md files: p5.js, git-point

CONTRIBUTING.md file

The CONTRIBUTING.md file is a short guide to potential contributors on how they can contribute to your open source project. You can see it as a pillar for your project, around which you’ll build a community and keep everything tidy. 

If you don’t have a CONTRIBUTING.md file but already have contributors to your project, build the file in collaboration with the core contributors. That way, they’ll feel a shared sense of responsibility, and you can create the best possible guide for encouraging new contributors. A sound CONTRIBUTING.md file includes:

• Welcoming note, saying that you’re keen for contributions;
• Table of contents, if your file is long, with links to different headings in your document;
• Pointers to key resources, like ROADMAP.md, issue tracker tool, and forum (if existent);
• Information on how to set up the development environment;
• Description of how to test the project and where the tests are located;
• Protocol to submit code changes, what response they’ll get, and expected timelines;
• Guidelines for the types of bugs contributors should tackle;
• Protocol to report bugs and issues;
• Protocol to suggest improvements or new features;
• Information on style guides and coding standards;
• Templates for pull requests and bug reports that contributors can copy and add context to;
• Description of the recognition model, with a pre-emptive “thank you for contributing” and listing any recognition contributors might receive for participating in your project;
• Description of the code of conduct and rules of your project;
• Ways to contribute to the project other than code;
• Links to communication channels for anyone who needs help and wants to ask questions.

💡 Examples of CONTRIBUTING.md files: Atom, GitHub docs

ROADMAP.md file

The ROADMAP.md file organizes the tasks that need to be done in your project. In addition, it helps potential contributors understand your project’s current status and where it’s going next. The roadmap can be as simple as a collection of issues in your issue tracker or a detailed timeline with milestones. If your roadmap is more than a list of issues, an inviting ROADMAP.md file includes:

• Presentation of the project, showing what you’re doing, for who, and why. You can adapt the summary in your README.md file and add a shorter version here.
• Description of how contribution can get involved. Point contributors to the parts of the project they can immediately work on and link to the CONTRIBUTION.md file.
• Timeline: the star of your roadmap. This section organizes all the tasks needed to complete your project around milestones, mapping out what you’re working on now and where it’s going. You can organize it around short, medium, and long terms items.

💡 Examples of ROADMAP.md files: PaperBadger, Harbor

LICENSE.md file

The LICENSE.md file provides information on the reuse and permissions associated with the code in your open source project.

There are several open source licenses with different terms and restrictions, but the most popular ones are Apache 2.0, BSD, MIT, Mozilla 2.0, and GNU general public licenses. To choose the best license for your project, check out the license.md website, or the choose a license page.

Foster an excellent open source community

An exciting project, excellent documentation, and a stellar onboarding make people want to contribute to your open source project for the first time. However, the community you build makes them return and keep contributing to your project.

You want to build a community of open-minded people that welcomes new joiners and communicates effectively with everyone, creating a respectful environment. In the end, open source project management is mainly about people management.

Nurture your community and create a respectful environment

• Give periodic project status updates.
• Answer as much and as fast as you can.
• Acknowledge when a new issue or bug is reported.
• Create automated or standard answers to manage users and messages for time efficiency.
• Always be welcoming and respectful in all types of communication.
• Be exceptionally polite when rejecting contributions, explaining your reasons.
• Assign a project or community manager to handle people and discussions.
• Mentor people who show interest in the project and want to learn and contribute.
• Give more rights on the project to people who earn them.
• Write clear rules about getting more rights and causes for being banned (in the code of conduct section of your CONTRIBUTING.md file).
• Remember that contributors come from around the world with different backgrounds, cultures, and native languages. Stay open and tolerant.

Finally, contributing to other open source projects is a great way to experience first-hand how project management works. You can see what you like and dislike in different projects and make adjustments to your project based on that information.

[Live Talk] Maintaining Code Quality in Open Source

Would you like to hear an expert dive deeper into open source project management? Join Codacy CEO Jaime Jorge in an exclusive talk with Neils Lohmann, founder of the JSON for modern C++ on GitHub.