esup-multi

Arborescence des pages

Pourquoi ?

De base, un usage de GIT passe par des messages de commit clairs et concis, afin que les dev s'y retrouvent facilement en parcourant l'historique.
Cependant, à l'usage le maintien des commits peut s'avérer fastidieux et on peut rapidement s'y perdre dès lors que le projet devient volumineux.

Pour remédier à ce problème, des guides ont été pensés proposant des normes à respecter, imposant ainsi un style uniforme aux messages de commit.

L'un des guides les plus connus et souvent adopté est celui d'Angular : https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit

Les avantages d'adopter une norme de commit : 

  • Générer automatiquement des CHANGELOGs.
  • Déterminer automatiquement un changement de version sémantique (en fonction des types de commits inclus).
  • Communiquer la nature des changements aux membres de l’équipe, au public et aux autres parties prenantes.
  • Déclencher des processus de génération et de publication.
  • Faciliter la contribution des personnes sur le projet en leur permettant d’explorer un historique de commit plus structuré.

Le format

En suivant le guide d'Angular, voici à quoi doit ressembler un message de commit :

<type>[(optional <scope>)]: <description>
<BLANK LINE>
[optional <body>]
<BLANK LINE>
[optional <footer(s)>]

Le type

Le type indique le contexte du commit. Il donne l'information sur le type de changement opéré. Est-ce qu'il s'agit d'une nouvelle feature, un bugfix, de la mise à jour de doc, ... ?

Voici la liste des types disponibles (selon la convention) :

  • build : changements qui affectent le système de build ou des dépendances externes (principalement ajout / suppression de dépendances npm, makefiles, ...)
  • chore : fait référence à des tâches de maintenance, des travaux internes ou des actions qui ne modifient pas directement le code source, mais qui restent nécessaires pour maintenir et améliorer le projet (le plus souvent, utilisé pour la création d'une nouvelle release : chore(release): publish new release)
  • ci : changements concernant les fichiers et scripts d'intégration ou de configuration (Gitlab-CI, Docker, Jenkins, ...)
  • docs : rédaction ou mise à jour de la documentation
  • feat : ajout d'une nouvelle fonctionnalité (entre en corrélation avec MINOR en gestion sémantique de version)
  • fix : correction d'un bug (entre en corrélation avec PATCH en gestion sémantique de version)
  • perf : changements qui visent à améliorer les performances
  • refactor : changement dans le code qui n'est ni une correction de bug ou l'ajout d'une nouvelle fonctionnalité. Utilisé principalement lors de la réorganisation du code sans modifier sa fonctionnalité
  • revert : annule un commit précédent
  • security : le commit améliore la sécurité du projet ou résout une issue rapportée
  • style : changements qui n'affectent pas le sens du code (espace, formatage, points-virgules manquants, ...)
  • test : ajout de tests manquants ou correction des existants

Utilisation du symbole ! : Lorsque le type (ou scope) est suffixé d'un ! on indique que les changements introduisent une rupture de compatibilité (généralement au niveau de l'API).
On peut également indiquer BREAKING CHANGE: dans le footer du commit
Ces changements entrent en corrélation avec MAJOR en gestion sémantique de version.

Le scope (facultatif)

Le scope sert généralement à indiqué le package / module impacté par le commit.

Par exemple, si les changements ont un impact sur le microservice auth le scope sera alors (auth) tel qu'il est déclaré dans le fichier package.json.

Le résumé court (sujet du commit)

Il doit s'agit d'une description succinte des changements. En général, il ne doit pas dépasser 52 caractères. 

Il convient d'utiliser de préférence l'anglais (discutable suivant la portée du projet), et à l'impératif présent (add, change, update, remove au lieu de changed, removed ou bien changes, removes, ...).
Exemple : remove unnecessary variable toto in controller

Suivant les bonnes pratiques d'Angular, il convient également de ne pas mettre de majuscule au premier mot du message, ni de point à la fin.

Body (facultatif)

Permet d'expliquer plus en détail la raison des changements. De même que pour le sujet, on utiliser l'impératif présent.

La description dans le body ne doit pas dépasser 72 caractères.

Footer (facultatif)

Permet d'indiquer la présence d'un BREAKING CHANGE: et on y référence aussi parfois le ticket d'erreur associé.

Github fournit une liste de mots-clés qui peuvent être utilisés en footer pour lier le commit à une issue ou un PR :

  • Close
  • Closes
  • Closed
  • Fix
  • Fixes
  • Fixed
  • Resolve
  • Resolves
  • Resolved

Exemple : Resolves: #10

Exemples

Multi étant actuellement une architecture monorepo (client + backend avec µservices indépendants), on peut envisager une convention de nommage supplémentaire indiquant qui, du client ou du backend, est impacté par les modifications.

Ajout d'une feature permettant d'exporter son EDT au format ical sur son téléphone

feat(@multi-backend/microservice-schedule): add ical format

Modification des appels au microservice d'authentification => ajout d'un token supplémentaire nécessaire dans le body

feat(@multi-backend/microservice-auth)!: add new access token in POST /auth url
 
BREAKING CHANGE: client needs to provide the new access token when calling the POST /auth url

Correction d'un bug sur la recherche dans l'annuaire

fix(@multi-backend/microservice-contacts) : update card result background color in dark mode

Modification de docs

docs(@multi-backend/microservice-main): update main gateway README

Comment ?

Outils nécessaires :

Installation et utilisation locale

Installation et configuration

On veut une utilisation globale du linter sur le projet, on installera donc la dépendance au niveau du package.json à a racine (cf. centralisation des fichiers package.json via les workspaces).
Depuis un terminal, dans dev/ :

npm install --save-dev @commitlint/config-conventional @commitlint/cli

Créer ensuite un fichier de configuration .commitlintrc.json au même endroit avec la conf suivante : 

{
  "extends": ["@commitlint/config-conventional"],
    "rules": {
      "body-case": [2, "always", "sentence-case"],
      "body-max-line-length": [1, "always", 72],
      "header-max-length": [1, "always", 52],
      "type-enum": [2, "always", [
          "build",
          "chore",
          "ci",
          "docs",
          "feat",
          "fix",
          "perf",
          "refactor",
          "revert",
          "security",
          "style",
          "test"
      ]
    ]
  } 
}

Installer ensuite Husky. Cet outil va permettre de créer des hooks sur les commits GIT, et donc va nous permettre de valider le message du commit via commitlint avant que le projet ne soit commité.
Toujours au même endroit, depuis le terminal :

npm install --save-dev husky

Ensuite pour activer les hooks, il faut se rendre à l'endroit où se trouve le dossier de config .git/ soit tout en haut de notre projet (au dessus de dev/).

Depuis un terminal, se rendre donc à la racine du projet, et exécuter la commande :

npx husky install

Un nouveau dossier .husky/ devrait alors apparaître.

On va alors lui indiquer la commande commitlint à exécuter au moment d'un commit en ajoutant un hook commit-msg :

npx husky add .husky/commit-msg 'npx --no -- commitlint --edit ${1} --config $(dirname -- "$0")/../dev/.commitlintrc.json'

Un fichier commit-msg devrait apparaître dans le dossier .husky/ contenant la commande commitlint à exécuter à chaque commit.

Utilisation en local

A présent, dès lors que le message de votre commit ne répondra pas au nommage conventionnel, commitlint vous retournera une erreur et le commit ne passera pas.

Exemples de commit qui ne passe pas

Ici, le commit ne passe pas car le type (build, ci, fix, feat...) n'est pas précisé.

Ici, le type précisé (docker:) n'est pas autorisé par la liste des types définis par la convention de Angular.

Ici le commit ne passe pas car le sujet du message ne doit pas commencer par une majuscule.

Exemple de commit qui passe

Utilisation de l'outil commitizen pour faciliter la rédaction des commits

Installer commitizen sur le projet

$ npm install --save-dev commitizen

Ensuite, initialiser commitizen sur le projet, dans dev/

$ npx commitizen init cz-conventional-changelog --save-dev --save-exact

Modifier la conf de commitizen. Éditer le fichier package.json à la racine :

{
  ...
  "devDependencies": {
    "cz-conventional-changelog": "^3.3.0"
  },
  "config": {
    "commitizen": {
      "path": "./dev/node_modules/cz-conventional-changelog"
    }
  }
}

Une fois les modifications apportées au code et ajouté à GIT, il suffit d'exécuter la commande suivante :

$ npx cz


  • Aucune étiquette