Skip to content

doc: add "Troubleshooting" & "best practices" #12791

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
refack wants to merge 8 commits into from
Closed

doc: add "Troubleshooting" & "best practices" #12791

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
379eb50
doc: add "Tips, Tricks & Troubleshooting"
refack May 2, 2017
0d82ca0
add `ninja` tip
refack May 2, 2017
1cae879
Comment out the empty "tricks" section
refack May 2, 2017
565c788
fix typos
refack May 2, 2017
35527fb
[squash] fix line length
refack May 2, 2017
31d7e6b
Relocated RoT
refack May 2, 2017
d8f688e
Fishrock123 comments
refack May 5, 2017
07eaa6a
[squash]tree-factor
refack May 7, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Relocated RoT
  • Loading branch information
@refack
refack committed May 6, 2017
commit 31d7e6b27d5b1a66a1e293834336c5af24819ee8
43 changes: 43 additions & 0 deletions doc/guides/tips-tricks-and-troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,48 @@
# Tips, Tricks & Troubleshooting

## Rules of thumb

<details>
<summary><strong>Provide motivation for the change</strong></summary>
Try to explain why this change will make the code better. For example, does
it fix a bug, or is it a new feature, etc. This should be expressed in the
commit messages as well as in the PR description.
</details>
<details>
<summary><strong>Don't make <em>unnecessary</em> code changes</strong></summary>
<em>Unnecessary</em> code changes are changes made because of personal preference
or style. For example, renaming of variables or functions, adding or removing
white spaces, and reordering lines or whole code blocks. These sort of
changes should have a good reason since otherwise they cause unnecessary
<a href="https://blog.gitprime.com/why-code-churn-matters">"code churn"</a>.
As part of the project's strategy we maintain multiple release lines, code
churn might hinder back-porting changes to other lines. Also when you
change a line, your name will come up in `git blame` and shadow the name of
the previous author of that line.
</details>
<details>
<summary><strong>Keep the change-set self contained but at a reasonable size</strong></summary>
Use good judgment when making a big change. If a reason doesn't come to mind
but a very big change needs to be made, try to break it into smaller
pieces (still as self-contained as possible), and cross-reference them,
explicitly stating that they are dependent on each other.
</details>
<details>
<summary><strong>Be aware of our style rules</strong></summary>
As part of accepting a PR the changes <strong>must</strong> pass our linters.
<ul>
<li>For C++ we use Google's `cpplint` (with some adjustments) so following their
<a href="https://github.com/google/styleguide">style-guide</a> should make your code
compliant with our linter.</li>
<li>For JS we use this
<a hreaf="https://github.com/nodejs/node/blob/master/.eslintrc.yaml">rule-set</a>
for ESLint plus some of
<a href="https://github.com/nodejs/node/tree/master/tools/eslint-rules">our own custom rules</a>.</li>
<li>For markdown we have a <a href="https://github.com/nodejs/node/blob/master/doc/STYLE_GUIDE.md">style guide</a></li>
</ul>
</details>


## Tips

### Windows
Expand Down