Managing an open source project: steps, best practices and challenges

What is good open source project management? It should not be considered a checklist of boxes to tick off.

In essence, good open source project management is not a one-and-done activity. A well managed open source project attracts contributors and it gives any and every potential contributor a good experience. It’s an ongoing set of actions (and not reactions).

When software developers like working on a project, they’re more likely to come back and fix something in the future. That’s invaluable for a medium to larger project – especially one without support from a large commercial business.

This article explores the different aspects of open source project management. Particularly, it covers ways to improve your project management, assuming that the project’s goal is to attract more contributors

Forms of open source project management 

So what actions can project managers take if their goal is to attract more contributors? The actions separate out into two different forms – outreach actions and internal actions. 

Outreach actions 

1. Emailing and newsletters
2. Blog posts explaining new developments
3. Social media promotion

For these outreach actions, it can help to have a list of common questions and answers ready, like an FAQ in real life (except in a conversational way). Red Hat categorizes these outreach actions as medium-touch engagement.

Internal actions

Actions that focus on your project itself, like the documentation and defining your developer audience are actions that might appear ‘lower touch’, but these internal actions are no less vital, and include:

1. Onboarding new contributors
2. Clearing obstacles to contributions
3. Encouraging good open source citizenship throughout the project

While outreach actions are more obvious and therefore sometimes considered more important, focusing on the internal actions are also valuable – especially if you haven’t considered open source project management strategies before. The following sections explore internal actions in more detail.

Onboarding new contributors to open source projects

When every user opens your GitHub 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. The reason for this is that new visitors need to understand that open source projects are not ‘products’. They do not have things like Service Level Agreements (SLAs). It’s easy for users to mistake open source projects for commercial software that has SLAs. 

Having an introduction section helps new users to understand who the project’s audience is – who uses it in production, and what’s their discipline as a developer? Write to fit their needs. For example, you can write aspirationally, including content on the different use cases and projects that can be constructed from your software. You could include content on education, showing a quick start guide, or some interesting edge cases.

New contributors may also be outside of the developer discipline. Therefore, it’s helpful to these visitors if your project introduction includes some tips on what makes up a good set of information in an issue or bug report, and a note on the size of your project. By clearly providing this information, you’re also letting your contributors know when to expect a response to their report.

As an example, TinyMCE separates the introductory content and the contributor content into two separate files on the tinymce open source project.

Note: TinyMCE is a widely adopted rich text editor, the open source project management goal is less about outreach and contribution and more on encouraging visitors to try the project.

The TinyMCE CONTRIBUTING.md guide, as an example:

# The big Tiny monorepo
Welcome to the TinyMCE monorepo.
For TinyMCE itself look to the [modules/tinymce](modules/tinymce) folder.
…

## Getting started

Install [Node.js](https://nodejs.org/en/) on your system.

Clone this repository on your system

```
$ git clone https://github.com/tinymce/tinymce.git

```

Clearing obstacles to open source contributions

Git commands

While having experience with Git commands is essential, educating contributors on how Git commands work is contentious, and can be an obstacle for contribution.You can provide guidance and support via one of the many Git guides available or, depending on your time and resources, you can coach or mentor new contributors to the project, but it’s not recommended. Instead, we’d suggest you provide a standard, form answer to help potential contributors self-evaluate their skills – it can save you time and energy.

Commit message formats

One of the main obstacles to contribution, are commit message formats. To clear this obstacle, you can encourage users to include a commit message template, or automate a commit message format for your new contributors to follow. GitLab offers the ability to include an automated commit message.

At the very least, provide a template of what a good commit message format looks like for your project. A standard pattern is: 

Merge branch '%{source_branch}' into '%{target_branch}'
%{title - fixing, changing, updating the problem}
%{description, why change is needed}
See merge request %{reference}

Encourage good open source citizenship 

The fundamental principle of good citizenship is that sharing useful information makes solving the problems easier. Encouraging project visitors to share as much information as they can when they’ve encountered a bug or issue, is one main way to encourage good open source citizenship.

Since open source projects are more often than not distributed around the world, most interactions are text based. And it’s easy to interpret text in a negative light – especially if there’s conflict involved. By always assuming positive intent, and encouraging more information on reported bugs and issues, it can help promote good information sharing, and good citizenship results.

For example, implement a reporting template that asks:

1. “What's broken?” 
2. “How do I replicate this?  
3. It clearly shows how to replicate the issue and how the bug affects the community.

Project management steps

If you haven’t done so already, a practical step you can take to better manage your open source project is to find a ‘best contribution’ example, and use it to create a template of the standard needed for your project. 

Another step is to research the Linux foundation’s content. They’re a major source of open source software guidance, as is Opensource.com – another essential place to check for guidance. 

In the TinyMCE open source project, you can see many of these project management practices in action. If you’d like to contribute to our project, please check the issues listed, and read over the Contribution Guide. Contributing to a project is a great way to experience first-hand how open source project management works.