doc: add new documentation lint rule #18726

estrada9166 · 2018-02-12T07:36:03Z

Add 80 characters limit to docs.
Change docs to fit 80 characters per row.
Fix broken links in Changelog.md
Fixes: #18703
Refs: remarkjs/remark-lint#82

Also I had to change manually the documentation for tools/icu
the documentation is not clear to ignore files and with .remarkignore
it shows an error

The docs must be changed in order to follow the commit guidelines.

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

Doc, Tools

BridgeAR

In general this is LGTM.

BridgeAR · 2018-02-12T09:27:20Z

GOVERNANCE.md

    and
-    `https://github.com/search?q=commenter%3A${GITHUB_ID}++org%3Anodejs&type=Issues`
+`https://github.com/search?q=commenter%3A${GITHUB_ID}++org%3Anodejs&type=Issues`


Hm, these two changes look somewhat weird but I can imagine that the new rule will otherwise complain about it even though it should not?

BridgeAR · 2018-02-12T09:40:47Z

It would be great to ignore the changelog file but I guess it is not that bad if we don't. What do others think?

Besides that I am a bis surprised that the md files in docs are not linted. They are files that contain lines above 80 characters e.g. readline.md or tls.md.

@watilde is it possible to ignore files somehow?

BridgeAR · 2018-02-12T10:15:10Z

CI https://ci.nodejs.org/job/node-test-commit-light/256/

BridgeAR · 2018-02-12T11:43:32Z

@estrada9166 seems like the linter will now properly complain about the rest of the entries above 80 characters. Can you please also fix those? See https://ci.nodejs.org/job/node-test-linter/16080/console.

Those errors should also come up when executing make lint.

estrada9166 · 2018-02-12T12:48:09Z

@BridgeAR Sure thing! fixing right now!

benjamingr · 2018-02-12T15:30:52Z

@estrada9166 - thanks for stepping up and making a PR :)

@nodejs/collaborators - is everyone OK with an 80 character limit in our docs?

Personally I'm -0 on it. Making sure there are no strong objections since this is a style rule.

apapirovski · 2018-02-12T15:37:54Z

In theory I'm in favour of it but I would like some clarity re: the long URLs. Is the change highlighted by @BridgeAR above necessary? If so, that makes me look less favourably on introducing this rule without first fixing it upstream to be a bit smarter.

BridgeAR · 2018-02-12T15:37:56Z

@benjamingr we already try to uphold that limit in the docs. Just manually and that fails some times. Therefore the request to add the rule.

BridgeAR · 2018-02-12T15:41:26Z

@apapirovski long URLs should definitely not cause issues. In case we have issues with those, I would suggest we fix it upstream and then get this in.

@watilde do you know if there is an option for things like that? Otherwise, would you be so kind and implement such an option or give a short hint where to work on to get it fixed upstream?

estrada9166 · 2018-02-12T19:03:25Z

@BridgeAR I just updated CHANGELOG_V9.md and this was the result:

Should I continue changing changelogs?

BridgeAR · 2018-02-12T19:09:46Z

@estrada9166 as I pointed out, it would be good if we find a way to exclude those. So thanks a lot for the work you already did!

evanlucas · 2018-02-12T19:09:58Z

I'm -1 to including changelogs for this.

estrada9166 · 2018-02-12T19:15:18Z

I'll contine searching how we can ignore them, because when I add them to .remarkignore this is the result:

Also I found this issue

BridgeAR · 2018-02-12T19:24:34Z

@wooorm would you be so kind and take a look / give advice?

apapirovski · 2018-02-12T19:47:19Z

It doesn't seem like remark supports stacking multiple .remarkrc files and due to the length of time it takes to lint the docs, we can't just switch over to using the approach suggested in the issue link above. Seems like we would need to make changes upstream unless I'm missing something. 🤔

wooorm · 2018-02-12T20:14:00Z

@wooorm would you be so kind and take a look / give advice?

Ignoring: you can either go with globs to files (remark **/*.md !foo.md), or go with remark . and a .remarkignore file. In the latter case you let remark do the work of finding / excluding files!

It doesn't seem like remark supports stacking multiple .remarkrc files and due to the length of time it takes to lint the docs, we can't just switch over to using the approach suggested in the issue link above. Seems like we would need to make changes upstream unless I'm missing something. 🤔

Well, config files can be JS, and can link to other configs, so you can do:

// .remarkrc
{
  "plugins": [
    "remark-lint-something",
    "./some-other-file"
  ]
}

...and

// ./some-other-file.js
exports.plugins = [require('remark-lint-something-else')]

wooorm · 2018-02-12T20:14:51Z

P.S. feel free to ask specific questions, I’d love to help, but I am also a bit swamped with a course (on node 🎉) I’m currently giving!

apapirovski · 2018-02-12T20:27:50Z

Thanks @wooorm. Due to how everything is structured within Node.js repo, it seems the file within doc/changelogs/ would have to be somewhat like this:

{
  "plugins": [
    "../../tools/remark-preset-lint-node/",
    ["../../tools/remark-preset-lint-node/node_modules/remark-lint-prohibited-strings", false]
  ]
}

Specifying simply "remark-lint-prohibited-strings" seems to result in the remark resolution algorithm being unable to find it. Unless you have any other tips?

mcollina

I'm -1 to this change (I'm making this explicit with the big red cross).

I see too many changes in our changelog, which I would prefer if this didn't touch.

I think this change could impact backporting doc changes too

Can we pick up a number that reflects the current situation (or causes less changes)?
We could pick the limit based on the max line length we have in the changelog.

BridgeAR · 2018-02-12T22:56:19Z

@mcollina read the above discussion ;-)

estrada9166 · 2018-02-13T02:37:02Z

@BridgeAR My solution to exclude the changelogs is:
/makefile

LINT_MD_DOC_FILES = $(shell ls doc/*.md doc/api/*.md doc/guides/*.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)
	@echo "Running Markdown linter on docs..."
	@$(call available-node,$(run-lint-doc-md))
	@touch $@

Excluding them on LINT_MD_DOC_FILES = $(shell ls doc/*.md doc/api/*.md doc/guides/*.md), any consideration before pushing? Do we agree with this change?

BridgeAR · 2018-02-13T02:50:53Z

I think that is a pretty elegant and easy solution! In this case it is great because it is much faster than having to upstream a change first.

Just one more thing: I think it would also be good to exclude the CHANGELOG.md in root. I think if we have those out, we are good to progress further.

estrada9166 · 2018-02-23T14:27:06Z

@BridgeAR Done!

BridgeAR · 2018-02-23T14:41:29Z

Light-CI https://ci.nodejs.org/job/node-test-commit-light/316/

apapirovski

LGTM

Add 80 characters limit to docs. Change docs to fit 80 characters per row. PR-URL: nodejs#18726 Fixes: nodejs#18703 Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Anatoli Papirovski <[email protected]>

BridgeAR · 2018-02-23T16:29:45Z

Landed in a29089d

@estrada9166 congratulations on your first commit to Node.js 🎉
Thanks a lot for all your patience and your fast reactions! This was really good work.

estrada9166 · 2018-02-23T16:36:00Z

Thank you so much to all of you!! 🎉

MylesBorins · 2018-03-06T21:33:09Z

Should this be backported to v9.x-staging? If yes please follow the guide and raise a backport PR, if not let me know or add the dont-land-on label.

Add 80 characters limit to docs. Change docs to fit 80 characters per row. Backport-PR-URL: #19189 PR-URL: #18726 Fixes: #18703 Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Anatoli Papirovski <[email protected]>

Add 80 characters limit to docs. Change docs to fit 80 characters per row. PR-URL: nodejs#18726 Fixes: nodejs#18703 Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Anatoli Papirovski <[email protected]>

Add 80 characters limit to docs. Change docs to fit 80 characters per row. Backport-PR-URL: #19189 PR-URL: #18726 Fixes: #18703 Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Anatoli Papirovski <[email protected]>

Add 80 characters limit to docs. Change docs to fit 80 characters per row. PR-URL: nodejs#18726 Fixes: nodejs#18703 Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Anatoli Papirovski <[email protected]>

MylesBorins · 2018-08-07T22:31:51Z

Should this be backported to v8.x-staging? If yes please follow the guide and raise a backport PR, if not let me know or add the dont-land-on label.

BridgeAR requested a review from watilde February 12, 2018 09:31

BridgeAR approved these changes Feb 12, 2018

View reviewed changes

BridgeAR mentioned this pull request Feb 12, 2018

doc: enforce max-line-length lint rule #18722

Closed

4 tasks

BridgeAR removed the build Issues and PRs related to build files or the CI. label Feb 12, 2018

mcollina requested changes Feb 12, 2018

View reviewed changes

apapirovski approved these changes Feb 23, 2018

View reviewed changes

BridgeAR added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Feb 23, 2018

BridgeAR closed this Feb 23, 2018

estrada9166 mentioned this pull request Mar 1, 2018

[v8.x backport] doc: add new documentation rule #19065

Closed

3 tasks

MylesBorins added the backport-requested-v9.x label Mar 6, 2018

estrada9166 mentioned this pull request Mar 6, 2018

[v9.x backport] doc: add new documentation rule #19189

Closed

3 tasks

MylesBorins mentioned this pull request Mar 7, 2018

v9.8.0 proposal #19181

Merged

mcollina mentioned this pull request Mar 23, 2018

doc: wrap buffer.md at 80 characters #19546

Closed

3 tasks

targos removed the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Mar 24, 2018

targos mentioned this pull request Mar 24, 2018

[v9.x backport] doc: add new documentation lint rule #19572

Closed

MylesBorins added the backport-requested-v8.x label Aug 7, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: add new documentation lint rule #18726

doc: add new documentation lint rule #18726

estrada9166 commented Feb 12, 2018 •

edited

Loading

BridgeAR left a comment

BridgeAR Feb 12, 2018

BridgeAR commented Feb 12, 2018

BridgeAR commented Feb 12, 2018

BridgeAR commented Feb 12, 2018

estrada9166 commented Feb 12, 2018

benjamingr commented Feb 12, 2018 •

edited

Loading

apapirovski commented Feb 12, 2018

BridgeAR commented Feb 12, 2018

BridgeAR commented Feb 12, 2018

estrada9166 commented Feb 12, 2018 •

edited

Loading

BridgeAR commented Feb 12, 2018

evanlucas commented Feb 12, 2018

estrada9166 commented Feb 12, 2018

BridgeAR commented Feb 12, 2018

apapirovski commented Feb 12, 2018

wooorm commented Feb 12, 2018

wooorm commented Feb 12, 2018

apapirovski commented Feb 12, 2018 •

edited

Loading

mcollina left a comment

BridgeAR commented Feb 12, 2018

estrada9166 commented Feb 13, 2018 •

edited

Loading

BridgeAR commented Feb 13, 2018

estrada9166 commented Feb 23, 2018

BridgeAR commented Feb 23, 2018

apapirovski left a comment

BridgeAR commented Feb 23, 2018

estrada9166 commented Feb 23, 2018

MylesBorins commented Mar 6, 2018

MylesBorins commented Aug 7, 2018

doc: add new documentation lint rule #18726

doc: add new documentation lint rule #18726

Conversation

estrada9166 commented Feb 12, 2018 • edited Loading

Checklist

Affected core subsystem(s)

BridgeAR left a comment

Choose a reason for hiding this comment

BridgeAR Feb 12, 2018

Choose a reason for hiding this comment

BridgeAR commented Feb 12, 2018

BridgeAR commented Feb 12, 2018

BridgeAR commented Feb 12, 2018

estrada9166 commented Feb 12, 2018

benjamingr commented Feb 12, 2018 • edited Loading

apapirovski commented Feb 12, 2018

BridgeAR commented Feb 12, 2018

BridgeAR commented Feb 12, 2018

estrada9166 commented Feb 12, 2018 • edited Loading

BridgeAR commented Feb 12, 2018

evanlucas commented Feb 12, 2018

estrada9166 commented Feb 12, 2018

BridgeAR commented Feb 12, 2018

apapirovski commented Feb 12, 2018

wooorm commented Feb 12, 2018

wooorm commented Feb 12, 2018

apapirovski commented Feb 12, 2018 • edited Loading

mcollina left a comment

Choose a reason for hiding this comment

BridgeAR commented Feb 12, 2018

estrada9166 commented Feb 13, 2018 • edited Loading

BridgeAR commented Feb 13, 2018

estrada9166 commented Feb 23, 2018

BridgeAR commented Feb 23, 2018

apapirovski left a comment

Choose a reason for hiding this comment

BridgeAR commented Feb 23, 2018

estrada9166 commented Feb 23, 2018

MylesBorins commented Mar 6, 2018

MylesBorins commented Aug 7, 2018

estrada9166 commented Feb 12, 2018 •

edited

Loading

benjamingr commented Feb 12, 2018 •

edited

Loading

estrada9166 commented Feb 12, 2018 •

edited

Loading

apapirovski commented Feb 12, 2018 •

edited

Loading

estrada9166 commented Feb 13, 2018 •

edited

Loading