Please follow the style guide applicable to the language or task.
If possible, make atomic commits, which means:
- a commit should contain exactly one self-contained functional change
- a functional change should be contained in exactly one commit
- a commit should not create an inconsistent state (such as test errors, linting errors, partial fix, feature with documentation etc...)
A complex feature can be broken down into multiple commits as long as each one keep a consistent state and consist of a self-contained change.
Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
The header is mandatory and the scope of the header is optional.
The footer can contain a closing reference to an issue.
If the commit reverts a previous commit, it should begin with revert:, followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.
The type must be one of the following:
| Type | Description |
|---|---|
| build | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) |
| chore | Administrative and management tasks |
| ci | Changes to the CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) |
| docs | Documentation only changes |
| feat | A new feature |
| fix | A bug fix |
| perf | A code change that improves performance |
| refactor | A code change that neither fixes a bug nor adds a feature |
| style | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) |
| test | Adding missing tests or correcting existing tests |
The subject contains succinct description of the change:
- use the imperative, present tense: "change" not "changed" nor "changes"
- don't capitalize first letter
- no dot (.) at the end
- limit to 72 characters or less
Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes".
The body should include the motivation for the change and contrast this with previous behavior.
When only changing documentation, include [ci skip] in the commit body.
The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit Closes.
Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.
`fix(pencil): stop graphite breaking when too much pressure applied`
`feat(pencil): add 'graphiteWidth' option`
Fix #42
perf(pencil): remove graphiteWidth option`
BREAKING CHANGE: The graphiteWidth option has been removed.
The default graphite width of 10mm is always used for performance reasons.
- Include thoughtfully-worded, well-structured tests in the
./testsfolder. - Treat
describeas a noun or situation. - Treat
itas a statement about state or how an operation changes state.
To ensure consistency and quality all documentation modification must:
- Use Markdown
- Refer to brand in bold with proper capitalization, i.e.; GitHub, npm
- Prefer tables over lists when listing key values, i.e.; List of options with their description
- Use links when, the first you are referring to:
- a concept described somewhere else in the documentation, i.e.; How to contribute
- a third-party product/brand/service, i.e.; Integrate with GitHub
- an external concept or feature, i.e.; Create a GitHub release
- a package or module, i.e.; The
@seantrane/repomodule
- Use single backtick
codequoting for:- commands inside sentences, i.e.; the
docker runcommand - programming language keywords, i.e.;
function,async,String - packages or modules, i.e.; The
@seantrane/repomodule
- commands inside sentences, i.e.; the
- Use triple backtick
codeformatting for:- code examples
- configuration examples
- sequence of command lines
- Reference methods and classes in markdown with the custom
{}notation:- Reference classes with
{ClassName} - Reference instance methods with
{ClassName::methodName} - Reference class methods with
{ClassName.methodName}
- Reference classes with
To ensure consistency and quality throughout the source code, all code modification must have:
- No linting errors
- A test for every possible cases introduced by your code change
- 100% test coverage
- Valid commit message(s)
- Documentation for new features
- Updated documentation for modified features
Before pushing your code changes make sure there is no linting errors, i.e.; npm run lint.
Tips:
- Many linting errors can be automatically fixed, i.e.;
npm run lint --fix. - Your IDE may have a plugin to see linting errors directly in your editor and automatically fix them on save.
- All HTML/CSS must adhere to Google's HTML/CSS Style Guide.
- All Java syntax must adhere to Google's Java Style Guide.
- All JavaScript syntax must adhere to Google's Shell Style Guide.
- All JavaScript syntax should adhere to JavaScript Standard Style.
- All Angular syntax must adhere to The Angular Style Guide.
- Run
jslintortslintover your code.
- All PHP syntax must adhere to PSR-2 Coding Style Guide.
- All Python syntax must adhere to Google's Python Style Guide.
- Run
pylintover your code.
- All Ruby syntax must adhere to The Ruby Style Guide.
- Run
rubocopover your code.
- All Shell syntax must adhere to Google's Shell Style Guide.
- Run ShellCheck over your code.