The second law of thermodynamics states that entropy always increases over time. To put it another way, chaos overtakes order little by little. Open source software projects are no exception. The longer a project grows and survives, the more issues and unmerged pull requests it will accumulate. Unresolved problems from the past make it hard to keep up with new contributions.
Bots to the rescue. Automation can help welcome new contributors and let them know what to expect. Outsourcing this labor to robots eases the burden on maintainers, freeing up time for more important tasks. Such as reviewing all those Hacktoberfest pull requests that are pouring in.
In this post, I’ll show you 6 ways to improve your open source project with Probot. The improvements fall into two broad categories: warmly welcoming new contributors, and communicating project norms or expectations.
Probot is a Node.js framework for building GitHub Apps. Probot listens for webhook events that happen in a repository or organization, such as commenting on a pull request, creating a new issue, submitting a pull request, reviewing code, etc.
You can build your own Probot apps, or you can take advantage of the many open source ones that already exist. Hooray for not reinventing wheels!
As with any open source dependency or tool, it’s important to evaluate whether a project is receiving consistent maintenance before deciding to use it. As of the time of this writing, all projects referenced this post are still actively being maintained.
Getting started with Probot
To get started, you will need:
- an open source repository hosted on GitHub
- Admin rights to install Probot apps on the GitHub repository or organization
Some Probot apps are hosted, meaning you just need to install them -- no deployment required.
To install a hosted app:
- Go to the app page and click “install”
- Choose the installation scope. You can install the app for an entire org, or a single repository.
- The app will tell you what specific permissions it needs
- You can revoke the app from the same page if you ever change your mind
Probot apps for welcoming and inclusivity
All Contributors Bot
Open source projects are an ecosystem. It takes many kinds of contributions to make the project go. All Contributors Bot makes it easy to recognize contributors who test your app, design, seek funding, write bug reports, and more.
You use the bot by at-mentioning a GitHub user in a comment on a pull request or issue.
The bot then creates a pull request updating the README to recognize the contributor’s efforts. We’re using it for the Twilio Open Pixel Art project, where it works like a charm:
Since the bot must be manually invoked, make sure you are using it consistently with all contributors to reward their contributions.
Prosebot helps us write the docs, better. It’s like a linter for your prose, that helps you catch grammatical errors, typos, non-inclusive language.
These options can be turned on and off separately via a config file, if (for example) you want the inclusivity checks but don’t care about spelling.
Welcome Bot automatically messages new contributors who open an issue or pull request.
Automated messages can help maintainers communicate:
- Project norms, like “we use semantic commits around here” including an example of a semantic commit
- How long the contributor can expect to wait before receiving a response
- As many animated gifs and emojis as possible, to convey enthusiasm, warmth, and gratitude 💟💯😻
Probot apps for enforcing community norms
It’s easy for your GitHub issues to get cluttered with old problems that realistically will never be fixed. Stale closes issues if there have been no activity on the issue for a specified number of days.
After installing Stale, you need to create a configuration file to enable the bot. But first, you’ll want to make an announcement to your open source community. That announcement gives community members a chance to chime in on issues they care about, to keep them from getting closed out.
When I was an Atom Editor maintainer, I received lots of bug reports that didn’t have enough information to investigate. If you tag an issue
more-information-needed and the issue reporter doesn’t follow up within a specified period of time, No Response will automatically close the issue out.
Of course, the issue reporter can always reopen an issue if they want to restart the discussion. You’ll need to create a configuration file before No Response will take effect.
“I love figuring out who needs to review my code” said no developer ever.
There are many ways to assign code reviews, such as setting up a CODEOWNERS file. Auto Assign is a lighter weight solution that allows you to randomly assign individual reviewers or review groups to a pull request. Review groups are useful if, for example, you want to assign one person from a front end team and one person from a back end team to review a pull request. You can also configure skip keywords such as
wip (work in progress) so that reviewers only get assigned on pull requests that are ready.
Alternatives and next steps
At the end of the day, we all only have 24 hours to work with. Being an open source maintainer can be a time sink, especially if it’s not your day job. Probot is a boon for maintainers as it allows you to get time-saving automations up and running very quickly.
Probot isn’t just for open source. If your company uses GitHub for inner source, you can also take advantage of Probot apps to boost your productivity. Although, some apps might work differently on GitHub Enterprise or in a private repository.
Probot isn’t the only open source automation tool. You can also use GitHub Actions to streamline your workflows, although it’s still in beta and you’ll need to request access. GitHub actions are useful for longer running-applications, and can be written in any language you can run in a Docker container. To learn more, check out Sarah Drasner’s repo of awesome GitHub actions. The one that posts a Conan O’Brien gif when a build fails is my personal favorite.
What are your favorite open source automation tools? Let me know in the comments section below, or find me on Twitter as @annthurium.