Maintainer Guide

• Repository Checklist
• Preparing a Project for Open Source Contributions
  • Name, Description, Tags
  • Documentation
  • Issue and Pull Request Templates
  • Beginner Friendliness
  • Open Sourcing a Project without Expecting Contributions
• Best Practices for Maintainers
  • Communication with Contributors
  • Managing Expectations
  • Building Community
  • Avoiding Burnout
• Resources

Suppose you are a maintainer looking to open an open source project for contributions. In that case, this checklist will help you to get your repository into an excellent state to start receiving external contributions.

✅ Relevant name

✅ Description

Clearly describe what the project does and is for.

✅ Relevant tags

They should highlight their scope, stack, field, etc.

✅ README.md file

Important information about your project.

✅ CONTRIBUTIONS.md/CONTRIBUTING.md file

A contribution guide for contributors.

✅ Open source license

A project is not open source if it doesn't have a valid license.

✅ Code of Conduct (COC)

An excellent indicator of a healthy contributor's environment.

✅ Issue and Pull Request templates

Templates for making issues and pull requests.

A project in the wild doesn't need all those things, but it should have most of them.

Read the next section for a more detailed explanation of the points in the checklist.

Back to Top

We'll start with the natural beginning for evaluating an open source project: The descriptive fields that GitHub provides.

• It should have a relevant name.
• It should have a description clearly describing what the project does and is for.
• It should have relevant tags highlighting its scope, stack, field, etc.

These are the first and most straightforward ways GitHub uses to recommend your content to potential contributors.

If you want your open source project to participate in Hacktoberfest, adding the hacktoberfest tag to your repo description is essential.

An example of a good name, description, and tag:

Good documentation is the best indicator that a project is well maintained, supported, and has a healthy and active community. There are a plethora of materials a repo can utilize to provide context to potential contributors, but the docs that matter most are:

The README

README is the face of your repo. It's the first thing anyone sees after the name and description, and it's the nexus for all content, links, docs, and other project associations. A project with a README is usually ready to accept contributions. Some basic things you should include in your README are:

• A more detailed project description than the description field in GitHub.
• How to install and run your application and provide a link to the document that explains it, if any. The more detailed, the better.
• A link to the Code of Conduct.
• Project status, roadmap, and other pertinent details for those interested in using or contributing to the project.

🔎 Example: Virtual Coffee's README

The Code of Conduct

The Code of Conduct (COC) is an excellent indicator of a healthy contributor's environment. There are many Code of Conduct styles online, and many projects use one of the standard templates. But it's always worth looking at a project's Code of Conduct before starting any contribution work. Not every open source project may necessarily have one. Some maintainers opt to describe appropriate behavior in the README file.

🔎 Example: Virtual Coffee's Code of Conduct

The Contributing Guide

Last but certainly not least, there should be some discussion of how to contribute to the project. Some write these instructions directly in the README, which is alright. Still, we prefer an explicit document that highlights the following:

• The recommended process for making issues/submitting pull requests.
• What to do if you feel somebody violates the Code of Conduct?
• How to communicate with maintainers? How often should you expect interactions/reviews, and through what mediums?

🔎 Example: Virtual Coffee's Contributing Guide

The License

Many popular and vetted open source licenses make it easy and safe for people to contribute to a particular project. Unless you are a lawyer or have access to one, it is advised to use one of these.

🔎 Example: Virtual Coffee's open source license

These templates guide potential contributors in making issues and pull requests to the project. They remove much burden from the maintainer and the contributor from guessing the appropriate procedure for these contributions.

🔎 Example: These are Virtual Coffee's issue templates, and this is what users see when submitting a new issue.

Suppose you want to make your repository/project beginner friendly. In that case, you should have some indications in the documentation and processes that highlight that.

• Call to action
  Some repositories say "contributions welcome/beginner friendly" in the README or have tags on issues for beginners. Either way, there should be some indication that you do want someone to help.
• Healthy interactions with contributors
  Unless a project is brand new, it likely has some history of contributions from others. Looking at those interactions and how the maintainers work with contributors is a great way for contributors to get the "vibe" of the project. How often do maintainers respond? How do they respond? Are people appreciated for their work? If you intend to make your repository/project beginner friendly, bear this in mind.
• Clear tagging system in issues
  The easier it is to navigate the project issues and resources, the more friendly it is for new contributors.

Everyone has a slightly different definition of "beginner friendly", so the experience may vary in different repositories, which is okay.

If you want to open source your project so that other people can freely use the fruits of your labor, you don't have to do everything on the checklist.

For example, you won't need issue and pull request templates or a contributing guide. A Code of Conduct, however, is still recommended. Even if you are not expecting contributions, you may still get public activity on your repo, for example, on issues. It helps you set boundaries and keep conversations respectful.

Back to Top

Communication is key to running a successful open source project. Establish conventions for communications early on and make sure these are well documented. Many projects communicate via issues and pull requests. Some use external platforms such as Slack, a forum, IRC, or email lists. All are good ways to communicate. The important thing is to figure out what is most appropriate for your project. Using issues and pull requests is a solid choice if you still need to determine what is best.

Suppose you are maintaining a company project that is open to external contributors. In that case, you need to coordinate internal and external communication so that outside contributors can get essential updates communicated internally.

Regardless of the tools used to communicate, there are certain things to keep in mind to keep communication effective and respectful, especially in an international online space.

• Have a Code of Conduct
  All communication should follow the Code of Conduct.
• Messages should be kept short and straightforward
  It is often best to keep to 'one message, one topic'. However, there may be times when this is not possible. For example, if you will be unavailable for some time and need to respond to several points. If you need to discuss several topics in one message, put each in a separate paragraph.
• Keep the conversation respectful
  Disagreement and debate are healthy, but it is important to keep the conversation respectful. You could criticize people's ideas but don't criticize the person directly.
• Low-context communication in international, cross-cultural spaces
  Meanings should be explicit in the words you use. People from different cultures might not understand specific cultural references, cliches, and sayings.

Managing maintainers' and contributors' expectations is important to ensure a project's smooth running with external contributors.

Here are several things that maintainers can do to help manage the expectations:

• Breaking down tasks for external contributors into small, well-defined chunks.
• Ensuring that any preferences for code style, branch names, git workflows, etc., are well explained in the contributing guide or README.
• Communicating what support you can provide for contributors, if any (e.g., pair programming, answering questions, etc.).
• Communicating the availability and expected timescales for reviewing pull requests.

A strong community around an open source project can be crucial to the project's success. An active community around an open source project will help the maintainers handle support, spread the word, and bring new users and contributors to the project. They also allow maintainers to get feedback and new ideas to help the project fulfill the needs and aspirations of users.

Building a community takes effort and is equally important as the technical development effort. It is about both tools enabling community building and making and nurturing connections with and between people.

Things that will help build community:

• A place for discussion to happen
  It could be GitHub issues for smaller projects where the community focuses on project questions and development discussions. For larger projects or if you want to build a community in a broader sense, a separate venue such as a Slack or Discord community or forum will work better.
• A Code of Conduct
  It sets boundaries for interaction and keeps the community a welcoming space for everyone.
• Community documentation
  It explains how the community works and where to search for things related to the community. For example, we have our Virtual Coffee Handbook at Virtual Coffee.
• Leading with empathy and kindness
  You can go a long way to ease the journey of new people joining the community by welcoming them and helping them find their way there.

Maintaining an open source project can be a lot of work; many people do it simultaneously with their "day job". It is essential to be mindful of the risk of burnout and take steps to keep the work manageable.

Figure out a reasonable time frame for responding to issues and pull requests, and include it in your documentation. If you are maintaining a personal repository in your spare time, it's okay to say a week.

If you are maintaining a company repository, state your working hours in the documentation and clarify that you will only respond during office hours. Make sure you stick to this.

Back to Top

• Building Welcoming Communities
• An Introduction to Open Source

Back to Top