(a.k.a "Rules of thumb")
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.
Unnecessary 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
code churn 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.
Use good judgment when making a big change. If a reason does not 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.
As part of accepting a PR the changes must pass our linters.
- For C++ we use Google's
cpplint(with some adjustments) so following their style-guide should make your code compliant with our linter. - For JS we use this rule-set for ESLint plus some of our own custom rules.
- For markdown we have a style guide