Skip to content

Commit 9a79fe6

Browse files
committed
doc: add "rules of thumb" section
1 parent 7c238be commit 9a79fe6

File tree

1 file changed

+28
-0
lines changed

1 file changed

+28
-0
lines changed

CONTRIBUTING.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,34 @@ works.
3030

3131
This document will guide you through the contribution process.
3232

33+
### Rules of thumb
34+
35+
1. #### Provide motivation for the change
36+
Why will this change make the code better; does it fix a bug, is it a new
37+
feature, etc. This should be in the commit messages as well as in the PR
38+
description.
39+
2. #### Don't make _unnecessary_ code changes
40+
Things that are changed because of personal preference or style, like:
41+
renaming of variables or functions, adding or removing white spaces,
42+
reordering lines or whole code blocks. These sort of changes should have
43+
a good reason since they cause unnecessary ["code churn"](https://blog.gitprime.com/why-code-churn-matters).
44+
As part of the project's strategy we maintain multiple release lines, code
45+
churn might hinder back-porting changes to other lines. Also when you
46+
change a line, your name will come up in `git blame` and might hide the
47+
previous writer of the code.
48+
3. #### Keep your change-set self contained but at a reasonable size
49+
Use your good judgment when making a big change. If you can't think of a
50+
good reason but need to make a very big PR, try to break it into smaller
51+
pieces (still as self-contained as possible), and cross-reference them.
52+
You can also mark some of them as `blocked` pending the others.
53+
4. #### Be aware of our style rules
54+
As part of acceptance of a PR the changes must pass our linters. For C++ we
55+
use Google's cpplint (with some ajustments) so following their [style-guide](https://github.com/google/styleguide)
56+
should keep you in line.
57+
For JS we use this [ruleset](https://github.com/nodejs/node/blob/master/.eslintrc.yaml)
58+
for ESLint plus some of [our own custom rules](https://github.com/nodejs/node/tree/master/tools/eslint-rules)
59+
For markdown we have a [style guide](https://github.com/nodejs/node/blob/master/doc/STYLE_GUIDE.md)
60+
3361
### Step 1: Fork
3462

3563
Fork the project [on GitHub](https://github.com/nodejs/node) and check out your

0 commit comments

Comments
 (0)