From a54b5442a25664a312dd8a76b7e3372c4325108e Mon Sep 17 00:00:00 2001 From: ump45nose Date: Mon, 5 Oct 2026 04:05:14 +0800 Subject: [PATCH 1/2] docs: document Markdown conventions in CONTRIBUTING Contributors editing Markdown had no discoverable statement of what the house style actually is, so the same edits produced different results depending on who ran them. Prose in this repository is written one paragraph per line and is not hard wrapped, and one space follows a sentence period. Document both norms in CONTRIBUTING.md, the file contributors already read before opening a pull request. Also record that the 80-column wrapping in tool-generated files such as CODE_OF_CONDUCT.md comes from the generator, so it is left alone rather than "fixed". Closes: https://github.com/npm/cli/issues/5522 --- CONTRIBUTING.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a6cbabb062eb4..69d7c21ab8160 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,6 +44,15 @@ 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: + + - Prose is one paragraph per line and is **not** hard wrapped. Rewording a sentence then touches one line instead of three, which keeps documentation diffs reviewable. + - Code blocks, tables and headings stay on a single line. + - Use one space after a sentence period. + - 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%. From 3846fae3c94735086f48e45ce49db5ac50ec1767 Mon Sep 17 00:00:00 2001 From: ump45nose <52391318+ump45nose@users.noreply.github.com> Date: Thu, 22 Oct 2026 03:50:18 +0800 Subject: [PATCH 2/2] docs: address Markdown convention review feedback Use one sentence per line and separate paragraphs with blank lines. Apply the conventions to new content without incidental reformatting. Prepared with AI assistance. Validated Markdown rendering and diff scope. --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 69d7c21ab8160..11489be010642 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,9 +48,10 @@ We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). Markdown is rendered before it is read, so the length of a source line is a formatting detail rather than a content limit: - - Prose is one paragraph per line and is **not** hard wrapped. Rewording a sentence then touches one line instead of three, which keeps documentation diffs reviewable. + - 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. - - Use one space after a sentence period. + - 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