-
-
Notifications
You must be signed in to change notification settings - Fork 1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
(WIP) First draft of contribution guide.
- Loading branch information
Showing
9 changed files
with
292 additions
and
45 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,68 @@ | ||
# Writing an Actionable Bug Report | ||
|
||
We're a work in progress. You reporting bugs in a clear and actionable format is a big help. Thanks!! | ||
|
||
When writing a bug, please include: | ||
|
||
1. the steps you took to get to the defect (number the steps using a little markdown, as shown below). | ||
- what you *expected* to happen after the last step. | ||
- what *actually* happened after the last step. | ||
- information about your particular situation: | ||
* if it's happening while you're using the CLI, include the **redacted** output of `exercism debug`. | ||
* "redacted" meaning remove your API key from the output before including in the issue. | ||
- if its' happening on the website, include your OS and browser versions. | ||
|
||
## Example | ||
|
||
1. I recently completed the Hello World for Java. | ||
- I submitted the file (I got the success message). | ||
- I went to the link provided by the CLI. | ||
* **Expected:** to see my submission, | ||
* **Actual:** I got a 404. | ||
|
||
Here's my "exercism debug": | ||
``` | ||
**** Debug Information **** | ||
Exercism CLI Version: 2.3.0 | ||
Exercism CLI Latest Release: 2.3.0 | ||
OS/Architecture: darwin/amd64 | ||
Build OS/Architecture / | ||
Home Dir: /Users/jtigger | ||
Config file: /Users/jtigger/.exercism.json | ||
API Key: ******* | ||
Exercises Directory: /Users/jtigger/workspace/exercism/exercises | ||
Testing API endpoints reachability | ||
* API: http://exercism.io [connected] 350.644953ms | ||
* GitHub API: https://api.github.com/ [connected] 386.82533ms | ||
* XAPI: http://x.exercism.io [connected] 796.511395ms | ||
``` | ||
|
||
which formats to: | ||
|
||
- | ||
|
||
1. I recently completed the Hello World for Java. | ||
- I submitted the file (I got the success message). | ||
- I went to the link provided by the CLI. | ||
* **Expected:** to see my submission, | ||
* **Actual:** I got a 404. | ||
|
||
Here's my "exercism debug": | ||
``` | ||
**** Debug Information **** | ||
Exercism CLI Version: 2.3.0 | ||
Exercism CLI Latest Release: 2.3.0 | ||
OS/Architecture: darwin/amd64 | ||
Build OS/Architecture / | ||
Home Dir: /Users/jtigger | ||
Config file: /Users/jtigger/.exercism.json | ||
API Key: ******* | ||
Exercises Directory: /Users/jtigger/workspace/exercism/exercises | ||
Testing API endpoints reachability | ||
* API: http://exercism.io [connected] 350.644953ms | ||
* GitHub API: https://api.github.com/ [connected] 386.82533ms | ||
* XAPI: http://x.exercism.io [connected] 796.511395ms | ||
``` | ||
|
||
- | ||
|
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
*(This page needs to be written. See exercism/exercism.io#3253 for details.)* |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
# Roadmap | ||
|
||
## Overview | ||
|
||
Development efforts at the moment focus on making the core experience good: | ||
|
||
* smooth onboarding, | ||
- rich conversations, | ||
- high quality feedback, and | ||
- getting feedback quickly. | ||
|
||
### Smooth Onboarding | ||
|
||
From quickly/concisely conveying what a programmer (of various stripes) would get from participating in Exercism, to the actual path from zero to submitted exercise on any given track, it can be bumpy. | ||
|
||
Let's hunt down bits of waste particularly along this path and flatten them: extraneous words and confusing flows should be substituted for clear instructions and intuitive/guided next steps. | ||
|
||
The root of these efforts focus on User Experience (UX). The following are jumping-off points into those efforts. | ||
|
||
* call for help with UX in general: [exercism/discussions#34](https://github.com/exercism/discussions/issues/34). | ||
- conveying value and clear action on the homepage: [exercism/discussions#31](https://github.com/exercism/discussions/issues/31). | ||
|
||
### Rich Conversations | ||
|
||
Exercism is fundamentally a space that encourages programmers to talk about what's going on in their heads as they work and rework their code. That thinking bit is the heart of how individuals can become better. | ||
|
||
What can we do to encourage more and richer conversations among Exercism users? | ||
|
||
|
||
|
||
|
||
- supporting common workflows in profile, dashboard, and account pages: [exercism/discussions#33](https://github.com/exercism/discussions/issues/33) | ||
- and the solutions page: [exercism/discussions#32](https://github.com/exercism/discussions/issues/32). | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
*(This page needs to be written. See exercism/exercism.io#3251 for details.)* |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
*(This page needs to be written. See exercism/exercism.io#3252 for details.)* |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,16 @@ | ||
*(This page needs to be written. See exercism/exercism.io# for details.)* | ||
|
||
|
||
Please intend to help your fellow programmers improve. There is a [time](http://proco.stanford.edu/) and [place](https://www.codewars.com/) for competition, it's not here. | ||
|
||
## Tips | ||
|
||
Here's a collection on easy-to-digest bits; pick one at random for inspiration in leaving constructive feedback on submissions: | ||
|
||
- Make your feedback more digestible: start by pointing out something you really liked about this submission. | ||
- Imagine this person is you when you first started in the language. | ||
- With each challenge, include a piece of support. | ||
- What if you framed your feedback as a question to encourage curiosity, rather than a correcting directive? | ||
- Consider leaving a praise-only comment on this one. | ||
- Imagine you're warmly welcoming someone to your country when introducing them to the idioms and ways-of-thinking of the language. | ||
- Empathize: is your feedback worded in a way that you could easily take? |