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

docs: split off a CONTRIBUTING.md and improve formatting, grammar, links #313

Merged
merged 2 commits into from
May 5, 2022

Conversation

agilgur5
Copy link
Collaborator

@agilgur5 agilgur5 commented May 3, 2022

Summary

Split off CONTRIBUTING.md from README.md and improve a few pieces of it

Details

Wrote as two commits so that it's easier to review the diff. First is pure split, second is changes.

Split commit:

  • condenses the README a bit and uses the standard CONTRIBUTING.md file

    • it's a file I often look for when filing an issue or creating a PR
    • leaves the section still in the README so that users (esp. on NPM) will know to go there if they're not aware of that convention
  • GitHub also now tells users to read the CONTRIBUTING.md of a repo when filing issues or creating PRs, so hopefully this helps point more users in the right direction as well

Improvements commit:

  • slightly change reference to GH Issue Tracker

  • use oxford commas everywhere for clarity

  • missing "the" in a few places

  • more minor grammatical fixes (missing space, semicolon vs. comma, etc)

  • fix: "npm_modules" -> "node_modules"

  • fix: "npm lint" -> "npm run lint", "npm build" -> "npm run build", "npm build-self" -> "npm run build-self"

    • short-hand works in Yarn and for some pre-defined NPM scripts, like start and test, but the rest need run
  • "typescript" -> "TS" (prefer proper "TypeScript" or just "TS")

  • use backticks monospace/code formatting where appropriate

  • link to GitHub's official docs on forking and making PRs

    • also use the word "standard" instead of "normal" as it's more inclusive and reflective that this is a convention/standard
  • link to editorconfig site

  • link directly to .editorconfig with a relative link as well

  • reword portion about PR checks as they do run build and build-self nowadays (not sure how old this text is)

  • use an ordered list (instead of unordered) for the testing process as this is meant to be done in order

Preview / Markdown render

See this PR's CONTRIBUTING.md and README.md

Misc Notes

Still determining a balance between this CONTRIBUTING.md doc and steps in the issue template. The latter is going to be read much more often, but maybe it can have a checkbox of "I have read the CONTRIBUTING.md"? Some of the troubleshooting steps though I think are better spelled out in the issue template.

Related to #311 (comment)

- condenses the README a bit and uses the standard CONTRIBUTING.md file
  - it's a file I often look for when filing an issue or creating a PR
  - leaves the section still in the README so that users (esp. on NPM)
    will know to go there if they're not aware of that convention

- GitHub also now tells users to read the CONTRIBUTING.md of a repo when
  filing issues or creating PRs, so hopefully this helps point more
  users in the right direction as well
@agilgur5 agilgur5 force-pushed the docs-split-contributing-md branch 2 times, most recently from 993e4d5 to e6ab983 Compare May 3, 2022 16:43
- slightly change reference to GH Issue Tracker

- use oxford commas everywhere for clarity
- missing "the" in a few places
- more minor grammatical fixes (missing space, semicolon vs. comma, etc)

- fix: "npm_modules" -> "`node_modules`"
- fix: "npm lint" -> "npm run lint", "npm build" -> "npm run build",
  "npm build-self" -> "npm run build-self"
  - short-hand works in Yarn and for some pre-defined Node scripts, like
    `start` and `test`, but the rest need `run`
- "typescript" -> "TS" (prefer proper "TypeScript" or just "TS")
- use backticks monospace/code formatting where appropriate

- link to GitHub's official docs on forking and making PRs
  - also use the word "standard" instead of "normal" as it's more
    inclusive and reflective that this is a convention/standard
- link to editorconfig site
- link directly to `.editorconfig` with a relative link as well
- reword portion about PR checks as they do run `build` and `build-self`
  nowadays (not sure how old this text is)

- use an ordered list (instead of unordered) for the testing process
  as this is meant to be done in order
@agilgur5 agilgur5 force-pushed the docs-split-contributing-md branch from e6ab983 to d92133d Compare May 3, 2022 17:44
@agilgur5 agilgur5 changed the title docs: split off a CONTRIBUTING.md and improve, formatting, grammar, links docs: split off a CONTRIBUTING.md and improve formatting, grammar, links May 3, 2022
@agilgur5 agilgur5 added the scope: docs Documentation could be improved. Or changes that only affect docs label May 3, 2022
@ezolenko ezolenko merged commit e28d2f0 into ezolenko:master May 5, 2022
@agilgur5 agilgur5 added the kind: internal Changes only affect the internals, and _not_ the public API or external-facing docs label Jul 22, 2022
@agilgur5 agilgur5 deleted the docs-split-contributing-md branch July 2, 2023 21:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind: internal Changes only affect the internals, and _not_ the public API or external-facing docs scope: docs Documentation could be improved. Or changes that only affect docs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants