Automating new contributor issues with First Timers Bot

It's a new year and many of us have resolved to work in Open Source more. Maybe you want to contribute for the first time? Or maybe you are a maintainer of a project and want to have more contributors? Let me introduce you to my botfriend First Timers who will help you accomplish these resolutions.

Last year my friend Arlene and I worked on a Rails Girls Summer of Code project with Gregor Martynus from Hoodie as our mentor. Hoodie has these super awesome first-timers-only issues that guide new contributors through the contribution process. The problem was that creating these step-by-step issues would usually take the maintainer longer than to do the fix themselves. So Gregor asked us to build a bot that would automate this process. And so First Timers was born!

First Timers is a GitHub App built with Probot. Probot is a framework for building GitHub Apps in Node.js. It makes it really easy to set up a webhook for events that happen on the repository. You can see our webhook below. We are listening on the "create" event, and whenever something happens our function handleCreateEvent fires off. That's it! You can check out our code here (contributions welcome!).

module.exports = function (robot) {
  debug(`ready to receive "create" webhooks`)
  robot.on('create', handleCreateEvent)
}

To use First Timers, first you need to install the app on your GitHub repo. Then when you want to create a new issue, go to the file where the change will happen, make the change, and commit this to a new branch that starts with "first-timers-" along with a short message that describes what to do. First Timers will then check if this "create" event was a branch and if it starts with "first-timers-", and if these are both true, then it will open a new issue that looks like this.

The issue has a step-by-step guide, shows a diff of what the changes need to be, has a link to the file where the changes need to be done, and has labels like "first-timers-only". We have also added configuration which means you can change the labels, the template, or even create the issues on a different repository. Check out our Configuration section for more information.

First timers has been installed on over 200 projects, including Jekyll, Processing, and Semantic-Release!

So this is my call to action. Do you have typos that need to be fixed? Do you have copyright years that need to be updated? Do you want to help people make their first contribution? Install First Timers and start creating some issues!

Here's a short screencast Gregor made to show how it works.