luke
/
sbt
mirror of https://github.com/sbt/sbt.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Created Good-First-Issues (markdown)

Dale Wijnand 2018-04-10 16:27:23 +01:00
parent ba262f8e69
commit a8f4eff558
No known key found for this signature in database
GPG Key ID: 4F256E3D151DF5EF
1 changed files with 45 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
Good-First-Issues.md Normal file

@ -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.