Extract "The Contribution Workflow" from CONTRIBUTING.md

[jtigger]

(part of a larger effort to overhaul documentation around contributing: exercism/discussions#73)

CONTRIBUTING.md#submitting-code-changes outlines the workflow to contributing, from fork to pull request.

It would be incredibly helpful if this outline were extracted and written with first-time contributors in mind:

• extract this section into a separate file: docs/the-contribution-workflow.md (please use that name, other work (e.g. Add self-directed help section to CONTRIBUTING.md #3194) is referencing it).
• elaborate/annotate each action so first-timers can successfully follow the process.
  • currently, the flow assumes a contributor knows what "fork", "upstream", "remote", "pull request", "rebase" all mean. Link to existing documentation (ideally documentation that is aimed at first-timers) as much as possible.
  • it should be that someone who hasn't contributed on GitHub before can walk through the process and successfully submit a PR, properly.
• encourage readers to go to our support chat room (Gitter) and/or submit an issue to get assistance. We're here to help!!

[tejasbubane]

I think we should also add some build-related info - Travis, coveralls, etc. (Refer: #2973) and post-PR fixes - code changes, commit messages, squash, rebase, etc.

But I also think this might intimidate first-timers. For others, we should have a documentation to know what standards/practices we are following, what are the cases the build might fail and how to fix that.

So either we have separate sections in this doc itself or two new docs - one for newbies and one for experienced people. Something like we have for how-it-works http://exercism.io/how-it-works/newbie and http://exercism.io/how-it-works

[kytrinyx]

But I also think this might intimidate first-timers

Yeah, that's a good point. Would it help to make the documentation so you only have to read as far as the step that you're on? Kind of like what we've been doing with the launch checklists recently: exercism/prolog#1

[kytrinyx]

Can we point to https://guides.github.com/activities/forking/ and https://guides.github.com/introduction/flow/?

[josh-works]

Hey, I'd love to work on this. Since I am a first time contributor, I think I can get empathize with the target audience of this PR (other people like me who want to contribute).

What do I need to do to claim this?

(Also, 👋 from @turingschool!)

[kytrinyx]

@josh-works Awesome! I think you're right that you're in the perfect position to take this one on.

What do I need to do to claim this?

You just did!

Thank you ✨ 🌸 ✨

[kytrinyx]

(also 👋 to @turingschool! I think about you all often, wondering how you're doing)

One thing to be aware of: we're in the process of rebuilding/redesigning exercism.io. It might be worth writing up a generic contributing workflow in https://github.com/exercism/docs and then referring to it here. I don't know if that makes sense—let me know if it seems like a terrible idea.

[josh-works]

^^ sounds like a great idea. I'm back from the long holiday weekend, will be working on this shortly. I'll do a generic one, and link here and get feedback to make it awesome.

We're doing great over here at Turing School (well, as far as I can tell! It was perfect for me. I'm about done w/the last mod of the back-end engineering program, have learned a ton, and know enough now to be dangerous and go keep learning in "The Real World". So, wild success for me!

[kytrinyx]

A most excellent plan :)

"enough to be dangerous" is a fun place to be... and even funner if you know that this is where you are in the process.

[josh-works]

I'll add a quick note here - I'd appreciate some feedback on the above PR, at your leisure!

[dmcfaddengalway]

This would be my first contribution on GitHub but this seems like a good first project to contribute to. I have read the above but am still slightly confused. Is there anyone else I can talk to about this?

[josh-works]

@dmcfaddengalway welcome! 👋

I'm working on this particular issue right now. There's more discussion taking place under the open pull request, which lives here

It's still a work in progress (which is why the pull request title has [wip] in it) but if you're curious about the work in progress, this is the working draft, and Katrina added comments visible towards the bottom of this page

Is, that's the current state of this exact issue. If you're looking for other issues to contribute to, I would start with poking around issues with the "good first patch" label, or take a look at @first-timers-only.

[stale]

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.