From 0060c301ca0e782c73cf1caa803cceb6e610160d Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Mon, 14 May 2018 17:59:19 +0200 Subject: [PATCH] Simplify Good First Issues --- Good-First-Issues.md | 46 ++++++++++++++++---------------------------- 1 file changed, 17 insertions(+), 29 deletions(-) diff --git a/Good-First-Issues.md b/Good-First-Issues.md index 7f5c5dd..5d5fbb3 100644 --- a/Good-First-Issues.md +++ b/Good-First-Issues.md @@ -9,38 +9,26 @@ ## Criteria -To label an issue as a [good first issue][] is it must be: +To label an issue as a [good first issue][] it should: -* 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 +* follow the [issue template](https://raw.githubusercontent.com/sbt/sbt/1.x/ISSUE_TEMPLATE.md) +* be an accepted feature/enhancement request or a confirmed (and hopefully reproduceable) bug +* be approachable by a first time contributor, a good measure is it should takes a maintainer 20 minutes to + resolve (which translates to 1-2 hours for a newcomer) -## How-to write a good first issue (as a maintainer) +## Mentoring Instructions -As a maintainer these are the steps that should be taken to convert an issue (e.g a [help wanted][] issue) so -that it's ready for a new contributor do the following: +A [good first issue][] should include mentoring instructions that layout the steps to take to resolve an issue. -1. get familiar with the issue, and some of the associated code/tests/docs -2. make sure the [issue template](https://raw.githubusercontent.com/sbt/sbt/1.x/ISSUE_TEMPLATE.md) 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 concise +Steps: -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][]. +1. **Links**: Link to the relevant code, PRs, issue threads, docs, etc +2. **Solution**: Add comments/hints on how to resolve the issue (call out "non-solutions" if relevant) +3. **Testing**: Try and give testing tips, ideally link to prior art +4. **Help**: Explain how to ask for help (e.g ping @eed3si9n in the issue and/or on [sbt/sbt-contrib][]) +5. **Motivation** (optional): Explain the change's relevance or purpose (to motivate the contribution) +6. **Background** (optional): Explain the code's behaviour, structure, or context -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. +It's common that it takes longer to write mentoring instructions than to fix it yourself (as an experienced +maintainer) - this is an investiment in [making sbt easier to contribute to][] and a potential long-term +contributor, possibly maintainer.