Short Contributing primer document

[binyamin]

Problem

I find the size of the hosted docs (readthedocs) overwhelming. I imagine it's simply good documentation, but it's hard for me to skim.

Solution

I think a succinct primer for contributors would positively influence #1678 (looking for maintainers & contributors). Basically, a rudimentary contributing.md on GitHub. I think it should be on github, because it's much easier to stay on GitHub if you don't need in-depth docs.

I'm envisioning something with the following:

• Links to contributor & user support channels.
• Ways to help (PRs, triage, etc.)
• Important rules for PRs
• Setup-and-run guide

[binyamin]

FYI: The other day, I wrote up a general outline for contributing guidelines. https://github.com/binyamin/contributing
Also, I love writing docs, so I can start this.

[joshgoebel]

I find the size of the hosted docs (readthedocs) overwhelming.

Perhaps they just need better structure? But there is indeed a lot to learn once you get into the nitty gritty of actually building a grammar, or theme, etc...

I think a succinct primer for contributors ...

Not opposed here (at a high level) if this is done thoughtfully and with attention to detail. My primary worry would be we already cover SOME of this in our docs: building-testing, language-contribution, language-requests, etc. For better or worse we currently use .rst for docs and I don't want to see us merely including the same info verbatim (or almost verbatim) in two places... making it far more likely it won't be maintained.

So we'd have to balance any contributing.md with our existing documentation. Or make a very conscious decision that in some cases perhaps something should be moved out of docs and into contributing.

I definitely don't want this to just become a rst vs md or GitHub vs readthedocs battle.

[joshgoebel]

Links to contributor & user support channels.

All we really have right now is GitHub issues. Members of the core team have a Slack that we really don't use.

@egor-rogov @allejo What do you all think of opening up Slack or should be simply start a gitter or something else? I'm not opposed to a more official real-time "place", just I'm not sure it would really get lots/any of traffic...

Ways to help (PRs, triage, etc.)

I have a handle on most triage these days, but always glad for additional help (esp. those who know individual language intricacies). Lots of PRs tagged "help welcome" or "beginner friendly" although what beginner friendly means for our project might be a little higher bar than some since we're a grammar engine and regex and our own ruleset language is a large part of that.

Important rules for PRs

• Add a changelog entry to CHANGES.md
• Add your name to AUTHORS.txt under Contributors
• usually add markup tests if you've made a significant grammar change or fixed a bug
• change only what needs to be changed, don't re-lint/rewrite whole files when fixing bugs
• if we're going to improve linting (for files we needed to touch) it should be in a separate commit (and following our own eslint rules)
• often things are nuanced or far more complex than you initially thing - filing an issue for bugs or confusing behavior (providing opportunity for discussion) is often far better than just jumping in with a PR

Setup-and-run guide

This would be nice, again gotta figure out the balance with building-testing... I think setup-and-run might be a bit higher level piece of information and a bit "wider" though, not sure...

[joshgoebel]

A short section on our overall philosophy somewhere would be great also (I'm happy to help there):

• keep the core parser simple (focus on the 80%)
• encourage and support a plug-in culture (let others tackle the last 20%)
• we don't show line numbers on purpose
• we're more than a keyword highlighter
• we're not a full language parser
• auto-detect is not powered by magic unicorn dust

[binyamin]

@joshgoebel I appreciate how much thought you gave this. I'll get working on a first draft.

[binyamin]

@joshgoebel See https://github.com/binyamin/highlight.js/blob/binyamin-contributing-md/CONTRIBUTING.md

[joshgoebel]

Any reason we can't make this a WIP PR so I have all the usual github annotation tools?

[allejo]

All we really have right now is GitHub issues. Members of the core team have a Slack that we really don't use.

@egor-rogov @allejo What do you all think of opening up Slack or should be simply start a gitter or something else? I'm not opposed to a more official real-time "place", just I'm not sure it would really get lots/any of traffic...

Wait, there's a Slack channel?

I don't see the harm in opening up Slack. I personally am not part of any communities that use Gitter and I'm personally not looking to download yet another chat client on my computer.

---

I think there should definitely be a CONTRIBUTING.md file since GitHub will notify users of it when they open up a PR. My worry is that information would be duplicated between GitHub and RTD. I would like to see CONTRIBUTING.md focus solely on how to actually contribute to the project (like how to make PRs, a brief summary of the project structure, and commands to run). The rest of the more detailed docs (everything on RTD) should just be linked to from GitHub.