Beep Boop: 6 Bots To Better Your Open Source Project

October 03, 2019
Written by

6-bots-better-open-source-project

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 101

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

To install a Probot app that’s not hosted, you’ll need to deploy your own instance of the app on Glitch, Heroku, or GitHub Actions. See instructions here.

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.

screenshot of the All Contributors bot in action. In a comment, user annthurium says "@all-contributors please add @annthurium-test for design" and All Contributors bot then posts a comment with a link to the pull request it has created.

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:

Screenshot of an All Contributors attribution for the Open Pixel Art project. It includes 11 contributors who contributed code, and one who contributed feedback.

Since the bot must be manually invoked, make sure you are using it consistently with all contributors to reward their contributions.

Prosebot

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.

screenshot of GitHub Checks tab on a pull request where Prose Bot has been enabled. A spell check warning has been tripped, and the bot let the maintainers know "thiss" is misspelled and suggests some corrections.

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

Welcome Bot automatically messages new contributors who open an issue or pull request.

Screenshot of welcome bot in action on a GitHub issue. A new contributor opened an issue, and welcome bot responded with "Thanks for opening your first issue here! Be sure to follow the issue template!"

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

Stale

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.

Screenshot of Stale bot in action on an issue. Stale bot added a comment to an issue that says "This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions." Stale bot also added a "wontfix" label to the issue.

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.

No Response

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.

Screenshot of a bug report from the Atom Editor, in the form of a GitHub issue. User rsese asks for more information about a bug. no-response bot posts a comment letting the issue author know the issue will be closed due to lack of activity, and then closed the issue.

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.

Auto Assign

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.

gif of Conan O'Brien in a tie and button up shirt, with his blazer pulled up over his head, waving his arms and making a goofy face.

What are your favorite open source automation tools? Let me know in the comments section below, or find me on Twitter as @annthurium.