docs: split off a CONTRIBUTING.md and improve formatting, grammar, links #313
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- 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
force-pushed
the
docs-split-contributing-md
branch
2 times, most recently
from
993e4d5
to
e6ab983
Compare
- 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
force-pushed
the
docs-split-contributing-md
branch
from
e6ab983
to
d92133d
Compare
agilgur5
changed the title
agilgur5
added
the
scope: docs
agilgur5
added
the
kind: internal
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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
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"
startandtest, but the rest needrun"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
link to editorconfig site
link directly to
.editorconfigwith a relative link as wellreword portion about PR checks as they do run
buildandbuild-selfnowadays (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)