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:

  • feat 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:

  • feat/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
  • feat/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:

  • Follow conventional commits (see below)
  • Separate the subject from the body with a blank line
  • Limit the subject line to 50 characters
  • 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

Conventional commits

Please follow the default conventional commits so that a changelog can be automatically generated and the GitLab release can contain all relevant information.

If you commit is fixing an issue don't forget to add a reference to this issue in the commit message.

A commit message could look like the following examples:

  • a commit that fixes the issue number 123 (and update the version number of PATCH)
fix(ci): the continuous integration can now fail with an explicit error message

With the new test commande, the continuous integration is now more robust and fail with an explicit error message.

It is now more robust as it should succeed when the app is really able to run.

fix #123
  • a commit that adds a new feature (and update the version number of MINOR)
feat(order): the order can be modified by its maintainer

This feature was asked for a long time by our users, and is now available in la chariotte.

The order can be modified by its maintainer.
  • a commit that updates the minimum version of postgres (and updates the version number of MAJOR because of the breaking change)
chore(db): update postgre minimal version

Due to a bug in previous versions of postgre, the minimal version of postgre is now version 12.1.8.

BREAKING CHANGE: The minimal version of postgre is now version 12.1.8.

For version management, you can have a look at Semantic versioning.

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