mirror of
https://framagit.org/la-chariotte/la-chariotte.git
synced 2025-04-30 10:52:40 +02:00
66 lines
2.5 KiB
Markdown
66 lines
2.5 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`
|