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.
Top comments (6)
Interesting idea! Question: what's your security model? The issue template says that claiming an issue will add you as a "contributor". From a quick look I'm not seeing anything about forking, so I assume this means "collaborator" access privileges to the central repository. That's more access than I would want to give anyone automatically; collaborators can do a lot more than push a single branch. Am I missing something?
Hi Dian! The bot doesn't do anything regarding automatically adding contributors or giving any user permissions. Maybe we need to reword that part of the template to be more clear.
The way hoodie handles contributions is that the contributor comments on the issue "claiming" it. Then an admin invites that person as a collaborator. But for your project, if you prefer them forking the repo, then you can configure a new template with the steps that work for your project.
I see. Yeah, I wouldn't want to just hand out write access, but it's good that it's not tied to one way of doing things. It should probably be clarified in the template both so any security implications are more obvious & so whoever claims an issue isn't expecting instant access if the intent is for them to work in-branch on the central repository.
This is great, thanks.
This is pretty dope. I wanted to build a bot like this that listens to changes on a repo, but I didn't even know where to start. Just starred probot!
That's awesome! Good luck! If you run into problems or questions, the Probot Slack channel is great and super helpful.