Skip to content

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