almet/la-chariotte
1
0
Fork 0
mirror of https://framagit.org/la-chariotte/la-chariotte.git synced 2025-04-29 02:12:39 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
la-chariotte/docs/contributing/naming.md

2.5 KiB
Raw Blame History

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