Style Guides

April 11, 2023 ยท View on GitHub

Please follow the style guide applicable to the language or task.

Table of Contents

Git Commit Messages

Atomic commits

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.

Commit message format

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.

Revert

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.

Type

The type must be one of the following:

TypeDescription
buildChanges that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
ciChanges to the CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
docsDocumentation only changes
featA new feature
fixA bug fix
perfA code change that improves performance
refactorA code change that neither fixes a bug nor adds a feature
styleChanges that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
testAdding missing tests or correcting existing tests

Subject

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

Body

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.

Examples

`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.

Tests/Specs

  • Include thoughtfully-worded, well-structured tests in the ./tests folder.
  • Treat describe as a noun or situation.
  • Treat it as a statement about state or how an operation changes state.

Documentation

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/repo module
  • Use single backtick code quoting for:
    • commands inside sentences, i.e.; the docker run command
    • programming language keywords, i.e.; function, async, String
    • packages or modules, i.e.; The @seantrane/repo module
  • Use triple backtick code formatting 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}

Source Code

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

Lint

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.

Languages

HTML/CSS

Java

JavaScript/TypeScript

PHP

Python

Ruby

Shell