Public Lab Research note

This is part of a series on software-outreach.

Create a welcoming "first-timers-only" issue to invite new software contributors

by warren | October 31, 2016 03:10 31 Oct 03:10 | #13667 | #13667

We've been doing some serious outreach for our software contributor community -- that is, people who help us make and other Public Lab software, through coding, designing, testing, and other helpful tasks.

One way we've been doing this is through first-timers-only issues, which are written in a very engaging, welcoming way, far differently than the usual "just report the bug" type of GitHub issue. To read more about these, check out (the lead image is from their site), which really captures how and why this works, and is beginning to be a movement in open source coding outreach! Beyond the extra welcome, this also includes getting such well-formatted issues out in front of lots of people who may be contributing to open source software for the very first time.

It takes a LOT of work to make a good issue of this type, and we often walk through each step required to actually make the requested changes -- the point is to help newcomers understand that a) they're welcome, and b) what the collaboration workflow looks like.

Our current list of unsolved first-timers-only issues can be found here:

And we try to keep at least 3-4 of them in there at all times!

What makes a good first-timers-only issue?

Good issues for newcomers are usually just a few lines of code, and provide:

  • context for the change -- how it fits into the big picture
  • a clear description of what's wrong and/or what needs to be different
  • a link to the page on the live site where you can see where the change will go
  • a link to the lines of code that need to change
  • step-by-step instructions on making the change and submitting it
  • who to ask for help
  • friendliness!

You can see an example of one here:

It should take longer to write such an issue than it would take you to do the fix yourself if you're a coder. And you can start with an existing issue, such as a help-wanted issue, which have some of this information, but not the strict formatting or extra guidance and friendliness!

A standard template

Update: we now have a template we use with the first-timers-bot that has lots of excellent wording and nice emojis to be extra friendly! Find it here:

Good candidates to source from

We've especially marked some as fto-candidate issues if we think they'd make good first-timers-only issues, but haven't yet had the time to follow through with the formatting -- you can choose one and upgrade it:

Note: you need not be a coder to write this kind of issue, either! Much of this is just good formatting, context, and friendliness; for the parts about the actual fix, you can ask someone who's familiar with the codebase (like me!) to help out before finally labeling it.

Copy-paste that all into a new GitHub issue, and fill it out to describe the problem and the solution:

This template could surely be improved or refined -- please make any suggestions or ask questions in the comments below!


We learned about this outreach strategy in a talk by Gregor Martynus of the Hoodie project at a BostonJS meetup, and through further reading at and You can also take a look at this post on the Hoodie project for some tips about what makes a great issue description for new coding contributors.

I did this Help out by offering feedback!

People who did this (0)

None yet. Be the first to post one!


Just a note: what if someone else created the issue, but you want to post a "tidied up" version with more clear documentation? Try creating a new issue and leaving a comment on the old one, something like "moving to #343 for a cleaner presentation of the issue". Then the old issue can be closed.

Is this a question? Click here to post it to the Questions page.

Reply to this comment...

We've been doing everything right in my opinion, and that's perhaps exactly why we're having sp many new contributors already (I'm one of them :P). Anyway, a few more things we could learn from hoodie are:

1) Include a motivation section -- Why does this bug need to be fixed? How does it fit into the bigger picture? What must've caused this to happen in the first place? This could then be followed by the actual solution and then a list of specific list of steps to be followed.

2) Prerequisites -- Most of the time, there will be none, but this might help reinforce the fact that the issue is super-easy to solve and anyone can give it a try.

3) We need a contact/help section. Again, I don't know how to emphasise more on a better chat solution. Although one tends to incline towards Gitter for software-related chats, we could very well work on an alternate platform. Slack, for instance, is what Hoodie uses as well, and it could be used as a complete solution compared to just developer's chat. Looking forward to discussing this in this OpenHour, I suppose?

For now, we could ask the newcomer to ask on the issue discussion itself.

4) Emojis? I really don't know if they're really required, but Hoodie uses a lot of them, and they do help make the issue look a little more friendly. Need input regarding this one.

cc/ @warren

Is this a question? Click here to post it to the Questions page.

Reply to this comment...

Login to comment.