Split STYLEGUIDE out from CONTRIBUTING.md

[iamam34]

• Fixes split CONTRIBUTING.md into main guidelines and auxiliary docs #1508 (I kept every bullet point, just reordered and moved across files)
• Includes additional point "do not use token syntax in descriptions" as noted in brew: minor reword, don't use token syntax in desc #1495
• Does NOT address "how to explain origin of option names" Add convention to indicate origin of option names to Contributing.md #1018

Comments, edits, suggestions and questions welcome! Specifically, do we want to move some of STYLEGUIDE.md back into the main CONTRIBUTING.md document?

I've been inspired to contribute as part of Hacktoberfest 2017.

[CLAassistant]

All committers have signed the CLA.

[agnivade]

This is a non-trivial PR. I think the primary idea was to have an addendum sort of thing apart from the CONTRIBUTING.md. So that, normal users can read CONTRIBUTING.md and just be fine with it, and hardcore users can read the extra document.

You have taken out the formatting part and made it into a separate doc. Ideally I wouldn't want anything removed from CONTRIBUTING.md and just a link to the auxiliary page with the extra added guidelines.

Please wait for @waldyrious to take a look and comment on this.

[sbrl]

Thanks for the PR! This is a rather interesting issue, as we'd like to keep at least something in CONTRIBUTING.md. Perhaps we can put a summary in CONTRIBUTING, and link to the style guide for more information? I certainly agree that a style guide would be useful though.

@waldyrious - what do you think?

[iamam34]

A summary in CONTRIBUTING sounds like a good idea; it seems like I should wait for comments from @waldyrious before going ahead with it.
What do you mean by "auxiliary" guidelines? Are there any parts of the current CONTRIBUTING.md that could be considered auxiliary?

[agnivade]

What do you mean by "auxiliary" guidelines?

That was the whole point of #1508. There are several guidelines which are not explicitly written down anywhere. Just something we have been using. Like not using tokens in the description, not referring to a person directly with "you".

You wouldn't know these until you have been a member of the org for several years. Hence, my suggestion to wait until @waldyrious takes a look at it.

[iamam34]

@agnivade I understand that I don't know any of the community's unspoken guidelines, but my intent with this PR was to create a space for y'all to add to as time goes on.

[stale]

Hi all! This thread has not had any recent activity. Are there any updates? Thanks!

[waldyrious]

Please accept my deepest apologies for the delay, @iamam34. Your contribution is very much appreciated :)

After discussing with the other maintainers on Gitter (transcript available here), we decided to preserve some of the content in CONTRIBUTING.md, in preparation for further reorganization of these documents. I took the liberty to rebase this branch to include these changes so that we can merge your PR sooner rather than later.

You'll get pinged to comment on the upcoming PR, but in the meantime, if you have any comments about the resolution of this PR, let us know :)

[waldyrious]

Ah, crap. It looks like editing fork branches on PRs doesn't work very well when the PR branch is the primary one of the fork, as was the case here. Sorry about that. I'll open a new PR, but the commits should remain attributed to @iamam34.

[waldyrious]

Notes for future reference:

• the new PR (resubmission of this one) was Split STYLEGUIDE out from CONTRIBUTING.md #1594.
• cross-referencing issue Universal format (style guide) #131, which was closed when the page format guidelines were first added as part of the CONTRIBUTING.md file, in 8d6fa52.