Good First Issues

Good First Issues

Criteria

To label an issue as a good first issue is it must be:

• reasonably self-contained
• approachable by a first time contributor (a good entry point)
• should take an experienced maintainer 15-20 minutes to solve, and therefore a newcomer about 1-2 hours

How To

To convert an issue (e.g a help wanted issue) so that it's ready for a new contributor do the following:

1. get familiar with the issue, and some of the associated code/tests/docs
2. make sure the issue template is followed (steps/problem/explanation/notes) so it's clear what is wrong and/or what needs to be different
3. make sure the issue is still valid, e.g the bug is reproducable
4. make sure the purpose/relevance of the issue/change is clear (this helps motivate participation)
5. add links to relevant code (don't link too huge code blocks or too many links - it gets overwhelming), giving basic explanation of the code behaviour and structure, and explaining the context of the issue/change: how it fits in the big picture
6. add links to any relevant documentation about either the issue or the code (again not too many links)
7. explain how to solve the issue, either with the answer and a link to the line(s) to change, or with hints and suggestions to possible solutions and (specify which "solutions" are not acceptable, if any)
8. add links to pre-existing tests and give tips on how to test the change (if possible)
9. detail who the contributor can ask for help, and by which means (sbt/sbt-contrib, issue comments, etc)
10. make sure that any additional steps to take are explained or mentoring advice is given
11. finally, review the issue and see if you can make it more friendly and/or consise

In effect it should actually take longer to write the the issue than to fix it yourself (as an experienced maintainer), but that extra time is an investment in making sbt easier to contribute to.

By:

• providing step-by-step instructions on how to make the change and submit it
• making sure that all the tools that first time contributors need to hack are ready and immediately available
• and that every roadblock gives them a chance to get distracted is dealt with we can make a big impact on knowledge sharing and contributions to sbt.