[wip] Contribution for beginners #3604
Conversation
josh-works
force-pushed
the
contribution_for_beginners
branch
from
6b49615
to
3075a62
Compare
There was a problem hiding this comment.
I really like where this is going. I have a bunch of thoughts that I've added throughout. The biggest thing is that with the redesign I'd like to refocus the contributing guide away from the website and towards other parts of the project, maybe language tracks.
Also, I would love for it to live in the docs repository. It might make a good README.md in the contributing directory.
| @@ -0,0 +1,245 @@ | |||
| ## Contributing to Exercism | |||
|
|
|||
| Open source contributions can be intimidating! As you're looking around, wondering where to dive in, you might think everyone _else_ knows what's going on in the code base, or has better grasp of the language, or seems to be well known around the project. | |||
There was a problem hiding this comment.
I love this opening. It hits people right where they might be hurting.
|
|
||
| As a total beginner, where do you begin? | ||
|
|
||
| Right here. This guide will walk you through your first open source contribution. |
There was a problem hiding this comment.
And this is a great continuation of that opening. It's super welcoming and friendly.
|
|
||
| It's going to target the smallest possible fix (improving documentation), as a "bridge" to more complex contributions later. | ||
|
|
||
| First, go take a look at [Contributing to Exercism.io](https://github.com/exercism/exercism.io/blob/master/CONTRIBUTING.md#submitting-code-changes) |
There was a problem hiding this comment.
We've been slowly moving all of our project-wide documentation into the http://github.com/exercism/docs repository. It is still a bit of a mess, but there's a lot of good content, and some of it is even organized fairly well.
I'd love to have this basic guide be about contributing to Exercism as a whole, and maybe use one of the language track repositories as the example instead of the main website repository (long story, but we're doing a ginormous rewrite/redesign, and the website repo is going to go away sometime in the next couple of months).
If we go down the route of having the guide be about the language tracks, then I think maybe we could link to https://github.com/exercism/docs/tree/master/contributing-to-language-tracks instead of the site contributing guide. Or there might be another document that is better, but I think the contributing to tracks one is a pretty good starting point.
There was a problem hiding this comment.
Awesome. I'll take a crack at an update later this week. Thanks, @kytrinyx!
|
|
||
| First, go take a look at [Contributing to Exercism.io](https://github.com/exercism/exercism.io/blob/master/CONTRIBUTING.md#submitting-code-changes) | ||
|
|
||
| If not all of that makes sense to you, keep reading. This is for you. |
|
|
||
| ## Table of Contents | ||
|
|
||
| - [Find the right contribution](#find-the-right-contribution) |
There was a problem hiding this comment.
I would say "Finding" here to match format of all the other bullet points.
| - [Find the right contribution](#find-the-right-contribution) | ||
| - [Claiming that contribution](#claiming-that-contribution) | ||
| - [Working on the code](#working-on-the-code) | ||
| - [Submitting your contribution](#submitting-your-contribution) |
There was a problem hiding this comment.
Throughout the guide, it might make sense to point to other documents in the docs repo, as "deep dives" on a subject.
|
|
||
| Different projects have different ways of "claiming" an issue, but for Exercism, just drop a comment in there, [like so](https://github.com/exercism/exercism.io/issues/3252#issuecomment-312428804). | ||
|
|
||
| If it makes sense, someone from the project will jump in, offer some guidance, and (generally) be pleased with your offer. |
|
|
||
| # Working on the code | ||
|
|
||
| OK, you've got an issue, you've got approval to work on it. Now's the fun part. |
There was a problem hiding this comment.
I would say that you totally don't need approval. In fact... it's such a huge relief when people jump in and get started (even just a little bit) without asking for approval.
The only caveat is that there's a ton of issues that go stale and the maintainers sometimes lose track of what's open, and then a bunch of stuff turns out to be out of date. So as part of claiming, I would totally recommend asking if the issue is still relevant. If it is you'll get a quick thumbs up, and if not, the maintainers will generally add more context.
There was a problem hiding this comment.
My favorite phrase is
Unless I hear differently...
A comment to the tune of
Unless I hear differently, I'll start working on this issue...
Would be perfect. I'll update this to a "forgiveness, not permission" workflow.
|
|
||
| OK, you've got an issue, you've got approval to work on it. Now's the fun part. | ||
|
|
||
| Now you need to get Exercism running on your local machine. |
There was a problem hiding this comment.
Ahhh. OK, so this bit is going to change a LOT and I have no idea what it's going to look like yet, unfortunately. I'll know more in a few weeks. If we go with a "tracks" guide, then that's easier to define now (go look at their readme, and if they have one, the contributing guide, for how to get the exercises running locally).
There was a problem hiding this comment.
Perfect. I'll drop a note to this extent in the guide, and even add something like
by the time you read this, the setup steps might have changed quite a bit. Exercism is in the middle of some huge updates. If this guide seems out of date, and you've read this far, perhaps updating this out-of-date section of the guide could be your first contribution
There was a problem hiding this comment.
I believe Docker can do that (setting a local development environment) without pain
|
|
||
| # merge your changes into your master branch | ||
| $ git checkout your_working_branch | ||
| $ git rebase -i your_working_branch master |
There was a problem hiding this comment.
This is kind of technical, but merging is not rebasing. If you could describe all of this without saying "merge" that would make people who are good at Git twitch a lot less.
There was a problem hiding this comment.
oof, yeah. I originally described a merge workflow, and then looked at your contribution guidelines, saw "rebase workflow", and forgot to edit the comment on line 172.
Thanks for calling this out.
Letting us know both the WIP part and the "wants feedback" part is very helpful—you did this just right.
✨ 💛 🌻 💛 ✨ Welcome ✨ 💛 🌻 💛 ✨ Thanks so much for taking this on. It's very, very needed! |
|
|
||
| # Find the right contribution | ||
|
|
||
| As mentioned in the contribution guideline, take a look at the [open issues](https://github.com/exercism/exercism.io/issues). There's a lot here, so you might want to filter by `label:"good first patch"` [(like this)](https://github.com/exercism/exercism.io/labels/good%20first%20patch). |
There was a problem hiding this comment.
This label helped me find a suitable issue to work on. Not sure about the link to exercism.io repo after reading #r130772596.
Maybe it should lead to problem-specifications as it has more issues to work on at the moment
Correct me if I misunderstood something
There was a problem hiding this comment.
I would link to the good first patch label on the exercism org in general here:
|
|
||
| OK, you've got an issue, you've got approval to work on it. Now's the fun part. | ||
|
|
||
| Now you need to get Exercism running on your local machine. |
There was a problem hiding this comment.
I believe Docker can do that (setting a local development environment) without pain
|
|
||
| Make sure to select `exercism/exercism.io`, with `master` as the `base fork`, on the left, and `your_username/exercism.io` as the `head fork` on the right. You can choose to compare whichever branch has your changes on it, either `master` or a different branch you worked on. | ||
|
|
||
| If you need to collect feedback on your work, it is convention to label your pull request as a "work in progress", or "wip". |
| - [Rewriting history](https://www.atlassian.com/git/tutorials/rewriting-history) | ||
| - [Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) | ||
|
|
||
|
|
There was a problem hiding this comment.
Maybe here is a good place to mention Gitter chat since these git magic can be overwhelming for newcomers not familiar with it? Something like this:
Don't forget: If you got stuck or something went wrong you can always ask for help in [our support chat (Gitter)](https://gitter.im/exercism/support)
What do you think?
There was a problem hiding this comment.
100% agreed. I'm heading out of town for a few days (leaving in 30 min!) so I'll update and integrate your feedback when I return.
| This is perfect. Now, go update your current repo with the 'upstream' repo, just run | ||
|
|
||
| ```shell | ||
| git pull upstream master |
There was a problem hiding this comment.
git remote update
git checkout upstream/master -b "my_new_branch_based_on_upstream
_master"There was a problem hiding this comment.
oh, Docker... can you link me to a Docker guide? I've never actually used it, so it feels like it's more work than just forking/cloning a repo, but that's just my perception.
Right on w/the git commands, too. 👍
There was a problem hiding this comment.
Here it is: Docker and exercism.io (I haven't tried it yet myself).
And I don't think that it's required to cover Docker in this doc, it was just a quick thought.
|
Hi @josh-works, do you still want to continue working on this? |
|
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions. |
Resolves #3252
Per @jtigger's suggestion for a more detailed, beginner-friendly guide to contributions, I've taken a stab at writing that out.
I'm not positive of protocol here with the "Work In Progress" tag, but this is not yet ready to be merged, though I would like feedback on it.
I'm documenting some of this conversation in the tutorial, and will be snagging some screenshots as I go.
Things I will do before removing the WIP tag
Is there anything else I should plan on doing?
Also, I took a stab at the formatting for this guide, and after looking through this example "launch checklist", I realize I can style this contribution guide to be much more similar to that post.
Would this be an appropriate "refactor", @kytrinyx, @jtigger, or @tejasbubane?
Oh, PS: First time contributor here, not just to Exercism but OSS as a whole, so I'm happy to hear feedback and guidance.