diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a6cbabb062eb4..11489be010642 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,6 +44,16 @@ We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). - `docs`: For documentation updates. The result will be a new semver patch version of the package when it is next published. - `chore`: For changes that do not affect the published module. Often these are changes to tests. The result will be *no* change to the version of the package when it is next published (as the commit does not affect the published version). +## Markdown Conventions + +Markdown is rendered before it is read, so the length of a source line is a formatting detail rather than a content limit: + + - Write prose one sentence per line to make diffs easier to review. + - Separate paragraphs with a blank line. + - Code blocks, tables and headings stay on a single line. + - Apply these conventions to new content; don’t reformat existing text unless it’s part of a substantive edit. + - Files generated by tooling (for example `CODE_OF_CONDUCT.md`, which is marked "do not edit", and the Artistic License text in `LICENSE`) are wrapped at 80 columns by whatever generated them. Leave generated wrapping as it is, and do not rewrap those paragraphs in unrelated pull requests. + ## Test Coverage We use [`tap`](https://node-tap.org/) for testing & expect that every new feature or bug fix comes with corresponding tests that validate the solutions. Tap also reports on code coverage and it will fail if that drops below 100%.