doc: remove non-style information from style guide #17866
Conversation
|
I agree with @BridgeAR, it should probably be moved to another doc. Maybe something like this in diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d27959c6dc..987ae84bcd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -284,6 +284,10 @@ should follow the [Style Guide](doc/STYLE_GUIDE.md). Code samples included
in the API docs will also be checked when running `make lint` (or
`vcbuild.bat lint` on Windows).
+Mechanical issues, like spelling and grammar, should be identified by tools,
+insofar as is possible. If not caught by a tool, they should be pointed out by
+human reviewers.
+
For contributing C++ code, you may want to look at the
[C++ Style Guide](CPP_STYLE_GUIDE.md). |
I don't think CONTRIBUTING.md is the place for it. The audience for that document is people opening pull requests and issues. The correct audience here would be Collaborators and maybe a small number of other reviewers. Therefore, onboarding.md or (better IMO) COLLABORATOR_GUIDE.md. I'm not going to fight to keep this paragraph out of our repository, but I honestly don't actually think the text has much value. It's an aspirational thing that is generally agreed upon as a best practice in software. It's basically "tools, not rules" which is widely regarded as a best practice. Including it isn't much different than including DRY, KISS, and YAGNI in my opinion. We don't include those things, and we shouldn't include "tools, not rules". Now...ALL THAT SAID...I think maybe what really needs to happen is this line just needs to be changed to instruct people to run |
|
Updated. PTAL! |
Trott
force-pushed
the
style-guide-edit
branch
from
c167007 to
d4436e1
Compare
I think the idea is to suggest to reviewers that they avoid leaving style nits for things that we don't have lint rules for. Emphasizing |
Ah, yes, that makes a lot of sense. Thanks for the clarification/explanation. |
Yeah, I can do that. |
While I agree that tools should be used insofar as possible, that information does not belong in the style guide.
Trott
force-pushed
the
style-guide-edit
branch
from
d41e181 to
beaafb3
Compare
|
@BridgeAR et al.: I've added a comment to |
While tools should be used insofar as possible, that information does not belong in the style guide. Move to onboarding doc. PR-URL: nodejs#17866 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Khaidi Chu <[email protected]> Reviewed-By: Daniel Bevenius <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>
|
Landed in f51067a |
While tools should be used insofar as possible, that information does not belong in the style guide. Move to onboarding doc. PR-URL: #17866 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Khaidi Chu <[email protected]> Reviewed-By: Daniel Bevenius <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>
While tools should be used insofar as possible, that information does not belong in the style guide. Move to onboarding doc. PR-URL: #17866 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Khaidi Chu <[email protected]> Reviewed-By: Daniel Bevenius <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>
While tools should be used insofar as possible, that information does not belong in the style guide. Move to onboarding doc. PR-URL: #17866 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Khaidi Chu <[email protected]> Reviewed-By: Daniel Bevenius <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>
|
this didn't land cleanly on v6.x or v8.x so I opted to not land. Please feel free to change labels and open a backport |
While I agree that tools should be used insofar as possible, that
information does not belong in the style guide.
Checklist
make -j4 test(UNIX), orvcbuild test(Windows) passesAffected core subsystem(s)
doc