From a8f4eff5588d83681a9024088072f178083b9967 Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Tue, 10 Apr 2018 16:27:23 +0100 Subject: [PATCH] Created Good-First-Issues (markdown) --- Good-First-Issues.md | 45 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 Good-First-Issues.md diff --git a/Good-First-Issues.md b/Good-First-Issues.md new file mode 100644 index 0000000..23bdf5c --- /dev/null +++ b/Good-First-Issues.md @@ -0,0 +1,45 @@ +# Good First Issues + +[good first issue]: https://github.com/sbt/sbt/labels/good%20first%20issue +[help wanted]: https://github.com/sbt/sbt/labels/help%20wanted + +[sbt/sbt-contrib]: https://gitter.im/sbt/sbt-contrib + +[making sbt easier to contribute to]: https://developer.lightbend.com/blog/2018-02-01-sbt-1.2-roadmap/#making-sbt-easier-to-contribute-to + +## 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.