# Conventional Commits & Branch Naming

## **Summary**

- [Objective](#conventionalcommits&branchnaming-objective)
- [Conventional Commits](#conventionalcommits&branchnaming-conventionalcommits)
- [Recommended Types](#conventionalcommits&branchnaming-recommendedtypes)
- [Examples](#conventionalcommits&branchnaming-examples)
- [Python Example and Commit](#conventionalcommits&branchnaming-pythonexampleandcommit)
- [Branch Naming](#conventionalcommits&branchnaming-branchnaming)
- [Git Workflow based on develop](#conventionalcommits&branchnaming-gitworkflowbasedondevelop)
- [Team Best Practices](#conventionalcommits&branchnaming-teambestpractices)

## <a name="conventionalcommits&branchnaming-objective"></a>**Objective**
Standardize our commit messages and branch names to :

- Improve readability of Git history
- Facilitate automatic generation of changelogs
- Streamline teamwork and code reviews

The commit messages are **AUTOGENERATED** thanks to a tool called “[Commitizen](https://commitizen-tools.github.io/commitizen/)”. The CI/CD pipelines standards in Keyrus will reject commits that don’t follow the standard commit structure offered by commitizen.

Documentation of the tool is found here: <https://commitizen-tools.github.io/commitizen/>

This tool is a handy tool that replaces the git commit command.

Configuration is done through a .cz.yml file that is available on each project, directly at the root of the project


The commit structure declared in this file is explained hereafter:
## <a name="conventionalcommits&branchnaming-conventionalcommits"></a>**Conventional Commits**

#### <a name="conventionalcommits&branchnaming-format"></a> **Format** :

```bash
<type>[optional scope]: <description>
```

#### <a name="conventionalcommits&branchnaming-recommendedtypes"></a>**Recommended Types**
- **feat**: New feature
- **fix**: Bug fix
- **docs**: Documentation only
- **style**: (ruff things) Formatting, spacing, etc.
- **refactor**: Code refactoring without logic changes
- **test**: Adding or updating tests
- **chore**: Maintenance (configs, deps, etc.)
- **ci**: CI/CD configuration
- **perf**: Performance improvement

#### <a name="conventionalcommits&branchnaming-examples"></a>**Examples**
- feat(auth): add JWT authentication logic
- fix(api): fix 500 error on /users
- refactor(form): simplify useForm hook
- style: remove empty line

#### <a name="conventionalcommits&branchnaming-pythonexampleandcommit"></a>**Python Example and Commit**

```Python
def calcul(x, y, mode='add'):
    if mode == 'add':
        return x + y
    elif mode == 'sub':
        return x - y
    else:
        raise ValueError("Invalid mode")
```
Corresponding commit:

```bash
feat(calcul): add `mode` parameter to handle addition and subtraction
```

## <a name="conventionalcommits&branchnaming-branchnaming"></a>**Branch Naming**
Recommended Format:

```bash
<type>/<ticket-ID>-<short-description>
```

Examples:
- feat/1234-auth-jwt
- fix/5678-login-button
- refactor/9012-user-service

## <a name="conventionalcommits&branchnaming-gitworkflowbasedondevelop"></a>**Git Workflow based on develop**
- **main**: production
- **dev**: continuous integration of features

Standard process:

1. Create branch from develop: `git checkout -b dev/my_branch`
1. Commit with Conventional Commits: `uv run cz c`
1. Merge via Pull Request into `dev`
1. Merge `dev` into `main` for release

## <a name="conventionalcommits&branchnaming-teambestpractices"></a>**Team Best Practices**
- One commit = one logical change
- Clear, well-documented PRs
  - `git diff developp > new_branch`
  - make a clear PR comments about the changes
- Explicit and consistent commit messages