Rewrite GitHub intro

[gsnedders]

Originally posted as https://github.com/gsnedders/wpt-docs/issues/24 by @gsnedders on 10 Feb 2017, 17:58 UTC:

And can we please not call it a "101", because that seems needlessly culture-specific?

[gsnedders]

Originally posted as https://github.com/gsnedders/wpt-docs/issues/24#issuecomment-279456036 by @gsnedders on 13 Feb 2017, 17:09 UTC:

https://github.com/gsnedders/wpt-docs/commit/e2e87ac7751d685653016bcbc7f4c208e148fb54 renamed it.

[gsnedders]

Originally posted as https://github.com/gsnedders/wpt-docs/issues/24#issuecomment-279787642 by @gsnedders on 14 Feb 2017, 18:09 UTC:

I wonder if it's good enough with some slight cleaning up. I hate it, but it'll do.

[gsnedders]

Originally posted as https://github.com/gsnedders/wpt-docs/issues/24#issuecomment-279787680 by @gsnedders on 14 Feb 2017, 18:10 UTC:

(As for why I hate it: it's so verbose.)

[gsnedders]

Originally posted as https://github.com/gsnedders/wpt-docs/issues/24#issuecomment-279795205 by @gsnedders on 14 Feb 2017, 18:38 UTC:

@frivoal @fantasai does that seem okay to you?

[gsnedders]

Originally posted as https://github.com/gsnedders/wpt-docs/issues/24#issuecomment-279862310 by @fantasai on 14 Feb 2017, 22:52 UTC:

Link? :) I don't know what document you're talking about.

[gsnedders]

Originally posted as https://github.com/gsnedders/wpt-docs/issues/24#issuecomment-279866349 by @gsnedders on 14 Feb 2017, 23:10 UTC:

https://github.com/gsnedders/wpt-docs/blob/master/docs/_appendix/github-intro.md or https://gsnedders.github.io/wpt-docs/appendix/github-intro.html

[gsnedders]

Originally posted as https://github.com/gsnedders/wpt-docs/issues/24#issuecomment-279866650 by @gsnedders on 14 Feb 2017, 23:11 UTC:

Also I know @jgraham's opinion is that we are not best placed to write git/GitHub tutorials, and we should merely reference other material maintained by others.

[gsnedders]

Originally posted as https://github.com/gsnedders/wpt-docs/issues/24#issuecomment-279896132 by @frivoal on 15 Feb 2017, 02:01 UTC:

On the one hand, yes. On the other hand, I think we have a specialized workflow, and it is useful to write a tutorial on how to do the things we need in the standard way, so that people who're not into learning git, and merely into sending us something / reviewing something can do so without worrying too much about how that git thing works. After a while, when they want to learn more in depth, then sure, they should look elsewhere.

[gsnedders]

Originally posted as https://github.com/gsnedders/wpt-docs/issues/24#issuecomment-279980540 by @gsnedders on 15 Feb 2017, 10:58 UTC:

@frivoal I don't think we are using GitHub in any unusual way at this point?

[gsnedders]

Originally posted as https://github.com/gsnedders/wpt-docs/issues/24#issuecomment-279984642 by @jgraham on 15 Feb 2017, 11:18 UTC:

Yeah, I think our workflow is rather standard at this point. I'm rather sure there are "how to create a PR on GitHub without really caring about git" tutorials. I don't mind putting in a very bare-bones guide with a list of steps to clone the repo and so on, but we aren't going to do a better job of explaining how to use GitHub than people who are dedicated to documenting that workflow, and keeping the documentation up to date with changes.

[gsnedders]

Originally posted as https://github.com/gsnedders/wpt-docs/issues/24#issuecomment-280040212 by @frivoal on 15 Feb 2017, 15:23 UTC:

I don't think I agree. We (the CSSWG) have had on our wiki some set of instructions detailing how to install the VCS of choice, how to get the clone the repos, how to make changes, and so on. We made a pretty detailed version of this when we started using mercurial. We did not do that because we enjoy writing tutorials, but because we have repeatedly have had requests from key contributors to do so.

The git version of that guide was only a half-assed attempt since mercurial was an option until now, but with the repo switch it stops being one, so we should have this documentation because we were asked to.

Now, if there is a specific guide we can point to and say with confidence that following the exact steps listed there will result in things working (and that the guide does not contained lots of additional unneeded information), maybe we can do that instead of writing our own. But I do not like the idea of just saying that git is sufficiently documented already and that people should just look it up. Git was already publicly documented (and so was hg before that) when the request for specific instructions came.

Anyway, we now have that guide written down. It may not be perfect, but I don't see the downside in publishing what we have. If someone has energy to improve it, that's nice, and if not, what he have isn't wrong, and I'd keep it as it until we either get an explicit request for specific improvements, or decide that it has become sufficiently incorrect that it is harmful to have people follow these steps.

[foolip]

Current URL is https://web-platform-tests.org/appendix/github-intro.html

I think it's pretty ok, but has outdated images of how GitHub's UI looks and still assumes that submodules are needed.

"Your pull request will go into a queue and will be reviewed soon" is often not true...

I doubt that many people find their way to these docs. Cleaning it up seems low priority, just deleting it fine too IMHO.

[frivoal]

I agree that improving this is probably low priority, but I would strongly disagree with deleting it. It was written because people had specifically asked that it be written, and has been used as a reference by them since.

Many people can write simple HTML/CSS/JS, and therefore have sufficient skills to write tests (if they have the inclination to). The subset of these who can already use github and do not need documentation is large, but it is not 100%.

If this documentation became so outdated that it would be actively harmful, then deleting it may become a relevant option, but I do not believe this to be the case.