Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Short Contributing primer document #2753

Closed
binyamin opened this issue Oct 15, 2020 · 8 comments · Fixed by #2760
Closed

Short Contributing primer document #2753

binyamin opened this issue Oct 15, 2020 · 8 comments · Fixed by #2760
Labels
docs/website enhancement An enhancement or new feature

Comments

@binyamin
Copy link
Contributor

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
Copy link
Contributor Author

binyamin commented Oct 15, 2020

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 joshgoebel added docs/website enhancement An enhancement or new feature labels Oct 15, 2020
@joshgoebel
Copy link
Member

joshgoebel commented Oct 15, 2020

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
Copy link
Member

joshgoebel commented Oct 15, 2020

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
Copy link
Member

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
Copy link
Contributor Author

binyamin commented Oct 15, 2020

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

@binyamin
Copy link
Contributor Author

@joshgoebel
Copy link
Member

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

@allejo
Copy link
Member

allejo commented Oct 21, 2020

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs/website enhancement An enhancement or new feature
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants