# Naming Conventions

We're trying to enforce some naming rules for our work. The goal is to be consistent.

## Git branches

Each git branch should be named in the form `category[/ticket-ref]/description`.

`category` determines the type of change you intend to make within the branch:

- `feature` to add a feature to the project
- `fix` to correct a bug
- `test` for making changes that are not associated with any specified need
- `doc` for making changes related to documentation (readme in particular)
- `refactor` for making a change within the code without consequence on the application

You can add a category if needed, making sure the meaning is easily understandable from the outside.

Between the category and description, the Gitlab ticket reference related to the branch may be inserted.

The branch description, in English and in kebab-case, must briefly describe the purpose of the branch: the purpose for
which it was created without going into detail.

Good examples:

- `feature/72/improve-pdf-generation`
- `fix/117/deadline-increments-on-duplicated-commands`
- `doc/explain-conventions`
- `refactor/99/is_ongoing-to-is_open`

Bad examples:

- `fix-some-stuff`
- `readme`
- `feature/add-a-cool-ui-element-when-the-cursor-passes-over-the-calendar-where-the-user-can-also-choose-the-associated-hour`
- `fix/edit-order/views/order.py-to-replace-is_ongoing-by-is_open`

## Git commits

Commit names should consist of two parts: a subject and a body (optional).

The subject acts as the title of the commit; it often suffices by itself and should briefly explain the purpose of the
commit.
If needed, the commit message can be enriched with a body that allows for more detailed explanations of what was
modified and why (but not how!).

Commit names must follow these 7 golden rules to ensure uniformity in the project:

- Separate the subject from the body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line
- Do not end the subject line with a period
- Use imperative mood in the subject line (IMPORTANT)
- Limit the line size (*wrap*) of the body to 72 characters
- Use the body to explain the what and the why (and not the how)

Details of this method can be found in this tutorial: https://cbea.ms/git-commit/

Good examples:

- `Refactor system X for readability`
- `Remove deprecated method`
- `Release version 1.4.2`

Bad examples:

- `Changing behaviour of X`
- `add submit button.`
- `Edit order.py line 72 to improve efficiency by adding recursive algorithm`

## Merge Requests

When creating a merge request, there are a few rules to follow to ensure a global coherence in our merge requests names.

The main rules to follow are the following :

- Begin the merge request name with the number of the ticket surrounded by brackets.
- Follow with the name of the issue your MR intends to fix.
- If your MR is not directly related to an issue, describe clearly in a few words the aim of the MR.

Good examples :

- `[152] Add the possibility to order different items`
- `[245] Rename title of main page`
- `Corrected typo in page X`

Bad example :

- `112 Add the title to page X`
- `Corrected some stuff`
- `[152] Modified the main.py file to correct a typo at line 120 and refacto views to make it a bit clearer`