git-conventions.md

# Git Conventions

This article is a compilation of conventions for git. The goal is to help teams and open source projects by **proposing a uniform naming, versioning and methodology** across developers.

Those conventions are mainly focused around web development but can be applied by other development fields and **fit any project**.

Some conventions are inspired by:

* [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
* [Angular Commit Message Guidelines](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)

Note that conventions can be **applied with a certain degree of flexibility** to fit the needs, particularities or size of a project.

## Table of Content

* [Naming](#naming)
  * [Commits](#commits)
    * [Types](#types)
    * [Description](#description)
  * [Branches](#branches)

## Naming

This section is about naming things in git. We will go through commits, branches, pull/merge requests and issues.

### Commits

Naming commits accurately is important as a commit is the primary source of information about a modification in a codebase.

Going through a commits history and searching for a specific modification can be a headache if commits aren't handily named according to that modification.

Therefore, the commit message should be structured in a readable and handy fashion:

```sh
<type>([scope]): <description> ([issue/PR/tag])

# Example
git commit -m "fix: Changed default state on search component (#189)"
git commit -m "feat(lang): Added French translations (#26)"
git commit -m "chore(version): Bump (1.0.2)"
```

Depending on flexibility and commit frequency, you can use more than a single type in a commit if needed:

```sh
git commit -m "feat/docs: Added search autocomplete and docs in readme"
```

#### Types

Commit types can be (but are **not limited to**):

| Type     | Description                                                  |
| -------- | :----------------------------------------------------------- |
| build    | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) |
| ci       | Changes to the CI configuration files and scripts (example scopes: travis, circle, browser-stack, sauce-labs) |
| chore    | A change that does not affect the codebase (version bump, bundle update, ...) |
| docs     | Documentation only changes (readme, comments, typos, ...)    |
| feat     | A new feature is added                                       |
| fix      | A bug is fixed                                               |
| perf     | A code change that improves performance                      |
| refactor | A code change that neither fixes a bug nor adds a feature    |
| revert   | Reverting to an old version/commit                           |
| style    | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, ...) |
| test     | Adding missing tests or correcting existing tests            |

It is important to note that types are **always lowercase**.

#### Description

A commit needs to **describe accurately** what the changes are without needing to look at the source code. Furthermore, it needs to be **concise** as developers will lose a lot of time reading too much if going through a lot of commits.

Thus, the description is generally **a single sentence listing precise changes** without to much technical talk as the developer can see the source code for any further inspection.

```sh
git commit -m "style: Changed primary color, main title margin and header background image"
```

Descriptions are sentences so they will **begin with an uppercase** when it is relevant.

### Branches

Work in progress...