mirror of
https://framagit.org/la-chariotte/la-chariotte.git
synced 2025-04-30 19:02:38 +02:00
92 lines
No EOL
3.2 KiB
Markdown
92 lines
No EOL
3.2 KiB
Markdown
# 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`
|
|
|