This article outlines helpful information for your journey as an open source project maintainer.
Table of ContentsPermalink to “Table of Contents”
- Repository Checklist
- Preparing a Project for Open Source Contributions
- Best Practices for Maintainers
Repository ChecklistPermalink to “Repository Checklist”
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.
Preparing a Project for Open Source ContributionsPermalink to “Preparing a Project for Open Source Contributions”
This section addresses the minimum requirements, highlighting key areas and considerations to help you evaluate whether or not your open source project is ready for contributions. When Virtual Coffee determines the projects we highlight and recommend to our members, these are the things we look for and why. We hope it can serve as a guide to anyone who finds this document.
Name, Description, TagsPermalink to “Name, Description, Tags”
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:
DocumentationPermalink to “Documentation”
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:
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
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
Issue and Pull Request TemplatesPermalink to “Issue and Pull Request Templates”
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.
Beginner FriendlinessPermalink to “Beginner Friendliness”
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.
Open Sourcing a Project without Expecting ContributionsPermalink to “Open Sourcing a Project without Expecting Contributions”
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.
Best Practices for MaintainersPermalink to “Best Practices for Maintainers”
Communication with ContributorsPermalink to “Communication with Contributors”
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 ExpectationsPermalink to “Managing Expectations”
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.
Building CommunityPermalink to “Building Community”
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.
Avoiding BurnoutPermalink to “Avoiding Burnout”
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.