From 2e6a60ebb073930cf871f33a10b9390751cb5e33 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 15 Jun 2018 14:36:23 -0700 Subject: [PATCH 1/6] doc: wrap releases.md at 80 chars --- doc/releases.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/releases.md b/doc/releases.md index 902547ef994069..bbf70bbbfbee22 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -88,8 +88,8 @@ least one business day in advance of the expected release. Coordinating with Build is essential to make sure that the CI works, release files are published, and the release blog post is available on the project website. -Build can be contacted best by opening up an issue on the [Build issue tracker][], -and by posting in `#node-build` on [webchat.freenode.net][]. +Build can be contacted best by opening up an issue on the [Build issue +tracker][], and by posting in `#node-build` on [webchat.freenode.net][]. When preparing a security release, contact Build at least two weekdays in advance of the expected release. To ensure that the security patch(es) can be @@ -524,7 +524,8 @@ To announce the build on Twitter through the official @nodejs account, email To ensure communication goes out with the timing of the blog post, please allow 24 hour prior notice. If known, please include the date and time the release -will be shared with the community in the email to coordinate these announcements. +will be shared with the community in the email to coordinate these +announcements. ### 16. Cleanup From d65c3cd19eb6ee4984dd09d16212012a5699400c Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 15 Jun 2018 15:34:00 -0700 Subject: [PATCH 2/6] doc: correct styling of _GitHub_ in onboarding doc --- doc/onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/onboarding.md b/doc/onboarding.md index 0748c1be7dbb44..f6354aa6118737 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -144,7 +144,7 @@ onboarding session. (especially if it just has nits left). * Approving a change * Collaborators indicate that they have reviewed and approve of the changes in - a pull request using Github’s approval interface + a pull request using GitHub’s approval interface * Some people like to comment `LGTM` (“Looks Good To Me”) * You have the authority to approve any other collaborator’s work. * You cannot approve your own pull requests. From 7f586a31492ae64f9ec3f6bd393722a009701bf6 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 15 Jun 2018 15:35:03 -0700 Subject: [PATCH 3/6] doc: remove linking of url text to url Linking URL text to itself is superfluous. It will display as a link in GitHub anyway. Bonus: This makes it possible to wrap the line at 80 characters. --- doc/onboarding.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/onboarding.md b/doc/onboarding.md index f6354aa6118737..6b8e7491485969 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -206,7 +206,7 @@ needs to be pointed out separately during the onboarding. ## Exercise: Make a PR adding yourself to the README * Example: - [https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0][] + https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0 * For raw commit message: `git log ce986de829457c39257cd205067602e765768fb0 -1` * Collaborators are in alphabetical order by GitHub username. @@ -250,7 +250,6 @@ needs to be pointed out separately during the onboarding. [`git-node`]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md [`node-core-utils`]: https://github.com/nodejs/node-core-utils [Landing Pull Requests]: https://github.com/nodejs/node/blob/master/COLLABORATOR_GUIDE.md#landing-pull-requests -[https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0]: https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0 [Publicizing or hiding organization membership]: https://help.github.com/articles/publicizing-or-hiding-organization-membership/ [set up the credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials [two-factor authentication]: https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/ From 2b1e71142f658248ce6d7b0e80e38cb0d61d8b8e Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 15 Jun 2018 15:37:47 -0700 Subject: [PATCH 4/6] doc: wrap pull-requests.md at 80 characters --- doc/guides/contributing/pull-requests.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/guides/contributing/pull-requests.md b/doc/guides/contributing/pull-requests.md index 0da7022d101ed5..0ae30d5b7710ec 100644 --- a/doc/guides/contributing/pull-requests.md +++ b/doc/guides/contributing/pull-requests.md @@ -137,8 +137,8 @@ notes about [commit squashing](#commit-squashing)). A good commit message should describe what changed and why. 1. The first line should: - - contain a short description of the change (preferably 50 characters or less, - and no more than 72 characters) + - contain a short description of the change (preferably 50 characters or + less, and no more than 72 characters) - be entirely in lowercase with the exception of proper nouns, acronyms, and the words that refer to code, like function/variable names - be prefixed with the name of the changed subsystem and start with an @@ -456,7 +456,8 @@ Focus first on the most significant aspects of the change: 1. Does this change make sense for Node.js? 2. Does this change make Node.js better, even if only incrementally? 3. Are there clear bugs or larger scale issues that need attending to? -4. Is the commit message readable and correct? If it contains a breaking change is it clear enough? +4. Is the commit message readable and correct? If it contains a breaking change + is it clear enough? When changes are necessary, *request* them, do not *demand* them, and do not assume that the submitter already knows how to add a test or run a benchmark. From 302c2e0a066d99ae6f63d21d364e46d9f4733b37 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 15 Jun 2018 15:49:23 -0700 Subject: [PATCH 5/6] doc: wrap style guide at 80 characters --- doc/STYLE_GUIDE.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md index 610b012dda5570..5d0f4f14eb2a22 100644 --- a/doc/STYLE_GUIDE.md +++ b/doc/STYLE_GUIDE.md @@ -58,15 +58,19 @@ * Use a capital letter after the "Note:" label. * Preferably, make the note a new paragraph for better visual distinction. * Function arguments or object properties should use the following format: - * * \`name\` {type|type2} Optional description. \*\*Default:\*\* \`defaultValue\`. - * E.g. * `byteOffset` {integer} Index of first byte to expose. **Default:** `0`. + * ``` * `name` {type|type2} Optional description. **Default:** `value`. ``` + + * For example: * `byteOffset` {integer} Index of first byte to expose. **Default:** `0`. + * The `type` should refer to a Node.js type or a [JavaScript type][]. * Function returns should use the following format: * * Returns: {type|type2} Optional description. * E.g. * Returns: {AsyncHook} A reference to `asyncHook`. * Use official styling for capitalization in products and projects. * OK: JavaScript, Google's V8 + * NOT OK: Javascript, Google's v8 + See also API documentation structure overview in [doctools README][]. From e79f0379d20499d52c1dcef822b535cf04910bff Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 15 Jun 2018 15:56:53 -0700 Subject: [PATCH 6/6] tools: lint doc/*.md files Makefile tasks only lint doc/**/*.md files but omit files that match doc/*.md. This change adds these previously-omitted files to the list of files to be linted. --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 8bfd4e674a452b..c2edfe59a4595a 100644 --- a/Makefile +++ b/Makefile @@ -1044,7 +1044,7 @@ lint-md-build: tools/remark-cli/node_modules \ .PHONY: lint-md ifneq ("","$(wildcard tools/remark-cli/node_modules/)") -LINT_MD_DOC_FILES = $(shell ls doc/**/*.md) +LINT_MD_DOC_FILES = $(shell ls doc/*.md doc/**/*.md) run-lint-doc-md = tools/remark-cli/cli.js -q -f $(LINT_MD_DOC_FILES) # Lint all changed markdown files under doc/ tools/.docmdlintstamp: $(LINT_MD_DOC_FILES)