Git conventions

Branch names

Each branch name consists of a type that matches the main commit one, an optional issue id coming from a JIRA ticket or a Github issue and a description.

MOZAIC's Team is using JIRA as their project management tool
but other contributors may use Github issues as reference into MOZAIC

---

Commit message

Each commit message consists of a type, a scope and a description.

Commit message's lines cannot be longer than 140 characters! This leads to messages that are easier to read when looking through the project history.

We are automating the releases version numbers (SEMVER) and the generation of the changelogs files by parsing the commit messages.

That's why it's very important to follow the conventional commit conventions, and to be as clear as possible on the description you provide

Naming convention

Type

The type must describe the changes you have done :

• BREAKING_CHANGE : When your changes are not backward compatible with an older version
• feat : When you add a new feat like a new component or a new Gatsby functionnality but also a documentation additions into the website
• fix : When you fix a code bug, a typo in the website documentation, or a problem in the sketch libraries
• refactor : When you had to rework, rewrite code lines, but it does not affect the
• test : To add new tests (unit tests, integration tests etc...)

Scope (optionnal)

The scope should precise your changes scope:

• website/xxx : everything that has to do with the Mozaic website UI, like menus, tabs nav, Gatsby etc...
• onboard/xxx : documentation only like getting started, contributing sections and information pages.
• patterns/xxx : anything that is related to visual deliverables : code / design / doc / tokens / icons
• tools/xxx : any dev tool delivered to the end user like linters, PostCSS configs, tokens customization scripts etc
• chore/xxx : anything related to CI, devtools, scripts for Mozaic developers

Note: xxx refers to more precise scope. For example : patterns/buttons, website/menu

Subject

The subject contains a succinct description of the change:

• use the imperative, present tense: "change" not "changed" nor "changes"
• don't capitalize the first letter
• no dot (.) at the end
• don't use approximative terms like "some" or "any"

---

Breaking changes :

Definition :

A breaking change is a change that require a user actions for compatibility purpose when updating. A breaking change will trigger a Major version number (from 1.0.2 => 2.0.0).

Breaking changes managment

For the sake of stability, we try to group breaking changes together and plan them in a way that allow users to manage them in chunks.

In case the current version we are working is an alpha or a beta version (1.0.1-alpha-1), we do not add the BREAKING_CHANGE commit type or label.

Support strategy :

In case a breaking change need to occur, for example changing the name of a classe or a mixin, we should keep the old one available until its planned support ending date.

In that case it is the right call to duplicate the class, mixin or function to support the old behavior, to create the new feature in parallel, with a easy way for the user to switch from one to the other.

Code comments should be written in order to easily find pieces of code that need to be removed when the support for a feature is to be dropped (when releasing a new major version), and documentation should be written to let users know the necessary steps to follow when switching to a new major version of mozaic.

---

Pull requests

The pull request titles follows the same rules as the commit message and consist of a type, an optional scope and a description. You have to use the same convention described in the commit part. Most of the time your PR title will be the same as the commit message.

Labels

When creating a pull request on github, you need to select the related labels, they are usefull to scan and filter PRs :

• at least one types label (same as the commit types described earlier)
• at least one scope label (same as the commit scopes described earlier)
• an optional skill label : design or dev, witch is related to who needs to review your code. If you need both skills to review your PR, do not add any skill label.
• an optional [WIP] label with [WIP] written in front of your PR title : States that your PR is a work in progress and should not be reviewed, but it does not mean that you can't specifically ask someone to review the PR to get valuable inputs.

Manage the commit(s)

It is preferable to have only one commit by pull request, but pull requests commits will be squashed before being merged to the master.

The merged commit message will then be used in changelogs and releases informations .

You can manage your commits using 2 methods :

• Rebase your commit using the rebase interactive
• amend your commit before pushing to origin

See details in Git documentation.

Merging multiple commits into master

If for some reason you worked on multiple types, scopes, or tasks in the same pull request and conserving multiple commits to be documented in the changelogs and release informations seems the best options.

In that case the feature in the button require the feature on the dev tools, and both informations should be kept in the history, and for information purpose in the changelogs and release infos.

You should specifically inform the reviewer that both commit should be kept when merging into master.