This article was originally published on my personal blog.
Not long ago I wrote an article about tips for beginners to open source. It was to help some confusions beginners have when they contribute to open source projects. In this article, I will try to give out some tips for maintainers of open source projects.
I personally have been maintaining a couple of open source projects and I have learned a thing or two along the way, so I’m writing this in the hopes that it will help new or beginner maintainers. This is a general overview of being a maintainer regardless of the programming language, concept or type of open source project you are maintaining.
Make Your Contributing Guidelines As Clear As Possible
When contributors want to help out in your project, it’s gonna take them some time to look around and understand the structure and environment you have in your project. To avoid confusion and assumptions, and to make sure that a unified code convention is being used, you need to create a CONTRIBUTING.md file in your repository that will hold all the contributing guidelines needed for anyone to make a contribution. This will also help beginner contributors understand more clearly the steps they need to take to make a successful contribution.
Whether you need to add lines of code needed to set up the project, images, or any instructions necessary to understand how to contribute correctly, make sure it’s all detailed and clear. If your project consists of multiple parts, make sure to split the contributing guidelines into two parts detailing how to contribute to each of them.
Create Issue and Pull Request Templates
As a maintainer, you can create templates for issues and pull requests. This will help anyone that’s submitting an issue or PR to understand how they should explain what issue they are presenting or resolving. This will also help you understand the process of checking issues and PRs and make it unified to save you time.
What you should do is that you should create templates for the different types of issues you have or for the pull requests that will hold comments that will not be seen in the issue but will be seen by the contributors when creating it. It could be something like:
Issue templates reside in your repository under
.github/ISSUE_TEMPLATE whereas pull request template resides in
pull_request_template.md. GitHub also can guide you through creating them, making it easier for you.
Beginners to open source are always very intimidated and not sure how to start contributing (I know that because that’s how I was like, too). That’s why it’s very important to make sure your project welcomes beginners to contribute. This means that you should always leave some easy tasks and issues for beginners to take on. I suggest adding and making use of labels in your repository likes
help-wanted. Also, when assigning the issue make sure that any issue labeled with
first-timers-only are actually done by beginners.
Another thing you should do is to make sure to be patient and comprehensive with beginners. Take the time to instruct them how to finish a certain task. If you have a team of maintainers or reviewers in your project, make sure they do that as well.
In my own experience, helping beginners contribute to my projects leads to them suggesting new ideas and making more contributions with time. So, don’t look over making your repository a safe space for them, even if it’s just for parts of it.
This one isn’t a necessity, but for me, I like adding it in some of my projects, especially those that have a lot of contributors. All Contributors is a bot that helps you make your contributors feel recognized, and not necessarily just those who have contributed code to your project. Using their emoji keys to indicate the contribution type, you can recognize each contributor for the contribution they’ve made. It helps make contributors feel appreciated for their effort. It can add the contributors in a table in your README file by default, or another file in your repository that you can specify in the configuration. Take a look at an example of how it will look like.
An example of how it works is just leaving a comment on an issue or pull request like this:
@all-contributors please add @shahednasser for design
This will add user @shahednasser as a contributor for design. This also helps in making contributors that don’t necessarily contribute code feel recognized. For example, if someone suggests an idea, you can add them as a contributor for idea.
Make Use Of Actions
GitHub Actions can be very helpful in automating certain parts of your project. A simple example of a GitHub action is an action that uses prettier every time changes are made to the code in the repository. This maintains the same formatting of the code, regardless of who contributes. This is actually very important as a lot of formatting issues start happening as you get more contributors. You can also add actions for compilations, automatic comments, and much more. Anything that can be automated and will help make the repository clean and structured or will help contributors make their contributions easier, try to make it a GitHub Action.
Add Code Scanning and Dependabot
This depends on your type of project, but on GitHub, you can add Code Scanning that will scan your code based on the programming language used and make sure no vulnerabilities or security issues are introduced. To turn Code Scanning on and add code scanners, you can do this under the Security tab in your repository. I also suggest turning on Dependabot so that you will get a warning about any vulnerabilities in your dependencies.
Create a Community
One of the best parts about working on open source projects is the community you can create. Create a respective community. Make everyone feel welcome and appreciate every contribution you get. Create a healthy environment for anyone that wants to give back to the open-source community. This will make your project a safe space and will attract more contributors to it, who will help make your project bigger and reach higher levels.
Originally published at https://blog.shahednasser.com on March 24, 2021.