Starter Issues

posted by Gregor

Every open source project loves new contributors. But — and this is something we learned at Hoodie — there are lots and lots of people who would love to contribute to Open Source, but don’t know how.

So what is missing? There is a difference between welcoming Pull Requests and creating a contributor-friendly community. One thing that is working out very well for us are “starter” issues.

The extra mile

Putting a “starter” label on an issue is Hoodie’s red carpet that we roll out for new and existing contributors. Here is an example “starter” issue. We maintain a list of open starter issues at http://go.hood.ie/hoodie-starter-issues.

It might look like a lot of work compared to creating an issue that just states the problem, but you get faster at creating these once you get the hang of it. Plus, “starter” issues are often created as follow ups to quick issues created without much description. And the result is more than worth so small extra time investment.

The most important thing is the message an issue sends to someone who is new to the project. It shows that we clearly care about people coming here, that we want them to succeed and that we are here to help. It’s about people who want to contribute, and not about the project.

Step by Step

Pro Tip from @kentcdodds after watching this video: use the “y” key to for getting a link to the file at the latest commit by hash.

First, explain what the situation is right now, and how it will look once the issue is closed. This can be about a bug that must be fixed, about a feature that needs to be implemented, about a typo in the README, about a missing test…, whatever needs to be done.

After that comes the step-by-step list of tasks. We like to start by adding a link to the free video series How to Contribute to an Open Source Project on GitHub for people who have never started a Pull Request before, to get everyone on the same page.

The first actionable item is to claim the issue


- [ ] claim this issue (assign yourself or comment below)

Once someone claimed the issue, we replace the item with something like


- [x] claim this issue (@myusername)

If the issue involves writing code, then we link to a description on how to setup the repository and how to run tests


- [ ] [Setup repository locally](url-here) and make sure
      that all tests pass

If the issue involves an update to the README.md file, then this is the next item, something like this


- [ ] update the [README](link-to-readme-section): add
      `myLib.myMethod` in the same format the other APIs
      are documented

At Hoodie, we follow Commit Message Conventions. Instead of explaining why and how, we make actionable items for the separate commits we’d like to have


- [ ] Commit with `docs(README): myLib.myMethod`

Once the first commit is ready, it’s time to start the Pull Request. Even though we link the tutorial on how to contribute to open source above, we do it again, because it doesn’t hurt. We also give congratulations if this is going to be the first Pull Request for someone, because it means a lot to us :)


- [ ] Start a Pull Request. Set description to `closes #123`
      If this is your first, welcome :tada: :smile:
      [Here is a great tutorial](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)
      on how to send a pull request)

Once the PR is created, we check all the above boxes and replace the above item with something like


- [x] Start a Pull Request (#123)

where #123 is the number of the Pull Request. GitHub will automatically create a link to the Pull Request here.

If this issue is about code, a test needs to be written or adapted. We give guidance where the test needs to be added, ideally like to the files / lines


- [ ] Create a file `/test/unti/my-method-test.js` in
      [/test/unit](https://github.com/myuser/mylib/tree/master/test/unit).
      See [/test/unit/my-other-method-test.js](https://github.com/myuser/mylib/tree/master/test/unit/other-method-test.js)
      for comparison
- [ ] Add a check that `myLib.myMethod` is a function in [/test/integration/constructor-test.js](https://github.com/myuser/mylib/tree/master/test/integration/constructor-test.js)

Then we ask the contributor to commit and push the tests. This way the commit will trigger our continuous integration tests on Travis CI and will add a red × to the commit, so we can be sure that tests are failing as expected. Here’s an example of what I mean.


- [ ] Make sure that tests fail when run with `npm test`.
      Commit with `test: myLib.myMethod` and push

Now comes the fun part: Writing the code! We use a single item on the list to describe what the contributor should be doing. If helpful, we link to the right place and explain how the feature / bug fix can be implemented. But it is okay to keep it short and leave something for the contributor to figure out, that’s what’s fun after all ;) — And at this point the contributor should feel comfortable to ask for help if they get stuck. So often time we do:


- [ ] Implement :)
- [ ] Make sure tests pass when run with `npm test`.
      Commit with `feat: myLib.myMethod` and push

The work is done. Now someone else needs to review and merge the work.


- [ ] Someone else: review & merge

During the review it may turn out that something is not quite right, so the pull request needs amendments. The contributor can add more commits as long as needed. Once they are done, they can either squash the commits themselves if they know how to do it, or the reviewer does it for them.

It is very important that when the reviewer is cleaning up the commit messages, that they keep the original author. Nothing is more disappointing than a first pull request accidentally “stolen” by a reviewer. A custom author can be set with:


git commit --author="Pat Doe <pat@example.com>"

At the end of the issue we add ways to contact us, usually something like this:

Ping us in the Hoodie Chat or on Twitter if you have any questions :)

Please let us know if you have any suggestions on how we can further improve our starter issues — we love hearing from you <3

Beyond the extra mile

If the issue involves writing a test, then you, the issue author, can create it yourself. Comment the test out and push it to master. Then instead of asking the new contributor to figure out how to write the test, all the need to do is to uncomment it and see the tests fail. This idea comes from Kent C. Dodds who wrote about it in his piece on First Timers Only — one of our favourites :)

Benefits

The benefits of starter issues go both ways. For people new to the project, it lowers the barrier and makes contributing more fun. For maintainers, it’s a great way to empower more people to do code reviews, as they have a list they can follow and check items off of. More importantly, it is our hope that creating starter issues will become a part of the Open Source culture and a great format for community engagement.

See also

Thanks

I’d like to thank

for their input reviewing this post!