Skip to content

Latest commit

 

History

History
127 lines (81 loc) · 5.32 KB

CONTRIBUTING.md

File metadata and controls

127 lines (81 loc) · 5.32 KB
Raw

Contributing

Helper packages

We strongly recommend using the following packages to help you write your commit messages and contribute to this project:

  • pre-commit: A framework for managing and maintaining multi-language pre-commit hooks. This package will help you to run linters and formatters before committing your code.
  • git-message-hook: A git hook to validate commit messages. This package will help you to write commit messages that follow the conventions of this project.

For the first package, once it is installed, make sure to run

pre-commit install

in the root of the project to install the git hook and give it the right to run. The same has to be done for the second package by a simple

chmod +x .git/hooks/commit-msg

Size of commits

A commit must be self-contained and implement a single change in the codebase. Don't hesitate to split changes into multiple commits if needed.

For instance, if you start a feature issue and end up writing a utility, fixing a typo in the doc, updating a test dependency and then implementing your feature, this would be 4 commits:

  • feat: Add the fooToBar utility, ABC-1
  • docs: Fix typo in the Squirrel README, ABC-1
  • test: Update the Foo dependency
  • feat: Implement new Foo, ABC-1

If a commit has nothing to do with your original ticket, it should ideally be done later in another branch. Sometimes, that’s not possible (for instance if someone force-pushed a non-linted file and your linter won’t let you push, or if a test has a broken dependency). If that happens, the commit message may not need the ticket suffix as it’s a general maintenance commit.

Prefixes

The prefix qualifies the content of the commit , eg. "feat" to describe a new feature, "fix" for a bug fix, etc. Each prefix is linked with a versioning strategy used by semantic-release to increment (or not) the project version. For instance, “test” commits do not trigger the release of a new version.

  • feat: A new feature, ie. something that changes the behaviour of the code
  • fix: A bug fix in the code (warning: fixes to the tooling should use chore)
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code, eg. white-space, formatting, missing semi-colons (warning: do not use this for CSS changes! CSS changes are feat)
  • refactor: A code change that neither fixes a bug nor adds a feature, eg. moving a piece of existing code to a new util or renaming a class
  • perf: A code change that improves performance
  • test: Adding missing or correcting existing tests
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Example:

  • feat(header): Turn the color of the header bar into blue
  • style(auth): Harmonise whitespace in the auth module code

Scope

Scopes are optional words added in parentheses after the prefix. You don’t have to use them, but you can. If your project uses scopes, they must describe the area of the project that’s impacted, e.g. feat(auth), fix(contactPage), chore(ci), test(squirrelApi), etc.

Keep it consistent in your team so the same part of the code always uses the same topic. The goal of the scope is to help you search for all commits affecting one component in your code, so it’s important to always write them in the same way.

Message relevance

The message has to precisely describe, in English, the change brought by the commit, as follows. The first word is an action verb in imperative form. It is capitalised. No punctuation should be used. The message should be short.

prefix(scope): Message starting with action verb

History rewriting

On your local branch, when you’re ready to make a PR back to develop or master, take a moment to make sure the history is clean.

You can rewrite it if needed with git rebase -i.

A clean history helps reviewers understand what the PR is about and unstack the commits properly.

Branch naming

Branch type

Following the GitHub branch model, each branch should be prefixed with a specific type:

Feature branch

Used for specific feature work or improvements. Generally branches from, and merges back into, develop, using pull requests.

feature/

Bugfix branch

Typically used to fix develop.

e.g.: bugfix/xxx

Hotfix branch

Used to quickly fix production/staging branches without interrupting changes in develop.

Changes made in a hotfix branch have to be merged back to develop once merged into production or staging

e.g.: hotfix/xxx

Custom branch

The name of the branch, in English, reflects its content as close as possible with no extra wording (preposition, link-words, …) and no capital letters. All words are separated with a dash.

[prefix]/[action] [verb]-[description of the changes as accurate as possible]

Examples:

  • feature/turn-header-to-blue
  • bugfix/hide-squirels-everywhere
  • hotfix/repair-request-parser
  • chore/update-dependencies
  • test/add-unit-tests