Changelog et commit

Lors de la contribution aux projets de Khaganat¹⁾, il est important de générer des “changelogs” de bonne qualité.

Pour cela, quelques règles sont à respecter. En particulier, nos changelogs sont automatisés, créés via les commits ; cela demande d'utiliser une syntaxe particulière.

Extrait de https://port.numenaute.org/khaganat/mmorpg_khanat/khanat_gamedev_guide et amendé.

Les messages de commit se rédigent en anglais de façon à faciliter la collaboration internationale.

La structure est la suivante :

<type>(portée, facultative): sujet
<ligne vide> (si élément suivant présent)
Corps de description plus complète (un ou plusieurs paragraphes), facultatif
<ligne vide> (si élément suivant présent)
<pied de page>, facultatif

Voir les exemples plus bas.

Les types de commits possibles sont les suivants (par ordre alphabétique):

• ci : concerne le fonctionnement de la CI du dépôt (entraîne un changement de type bugfix dans le versionnement).
• docs : reprise de la documentation du code sans toucher aux fonctionnalités (entraîne un changement de type bugfix dans le versionnement).
• feat : ajoute une fonctionnalité qui doit être mentionnée dans le pied de page avec un hashtag et son numéro de ticket (entraîne un changement de type minor ou major, selon le cas, dans le versionnement).
• fix : résoud un bug qui doit être mentionné dans le pied de page avec un hashtag et son numéro de ticket (entraîne un changement de type bugfix dans le versionnement).
• refactor : refactorisation du code sans modifier son comportement, ajouter une fonctionnalité ou réparer un bug (entraîne un changement de type bugfix dans le versionnement).
• removed : effacement d’une partie jugée inutile, redondante ou obsolète (entraîne un changement de type minor ou major, selon le cas, dans le versionnement).
• security : gestion d’une vulnérabilité (entraîne un changement de type minor ou major, selon le cas dans le versionnement).
• style : reprise formelle du code sans en modifier le fonctionnement (typos, espacements, tabulations etc.) (entraîne un changement de type bugfix dans le versionnement).

Le cas échéant, il est possible d’ajouter de nouveaux types selon les besoins (se référer à la convention Angular ou Keep a Changelog par exemple). Il faut alors penser à modifier les scripts de génération de changelog en conséquence (ainsi que les conséquences sur les séquences de versionnement), et documenter ces nouveaux types ici.

Le type doit être écrit en minuscule, sans espace.

Indiquée entre parenthèses, en minuscule sans espace, elle permet de préciser éventuellement sur quel partie du code la modification porte. Elle peut être choisie dans cette liste :

• core : concerne le code de base, les systèmes essentiels au fonctionnement du programme
• ui : concerne l’interface utilisateur

Certaines portées sont spécifiques à certains logiciels :

• shading : concerne les shaders d’affichage (spécifique au client 3D)
• ia : concerne l’intelligence artificielle des créatures en jeu (spécifique au jeu)

D’autres portées peuvent être ajoutées à la liste au fur et à mesure des besoins.

Si le commit entraîne une rupture de compatibilité dans le code, le type doit se voir accoler un point d’exclamation avant les deux points, quel que soit son type (entraîne un changement de type majeur dans le versionnement). Il faut alors également lui ajouter un pied de page avec la mention « BREAKING CHANGE: » suivi de la mention de l’endroit où la rupture s’opère.

Laissant une espace après les deux points, il ne comporte pas de majuscule au début ni de point à la fin. Le sujet doit décrire en peu de mot le changement qu’opère le nouveau code.

Exemples de première ligne correcte :

feat(ui)!: change methods for IG windows, close #18
fix(core): address collision problems for player, close #37
feat: add color wheel for windows background, close #16

Facultatif, il permet de décrire de façon détaillée ce qui a motivé les choix opérés et mettre l’emphase sur les améliorations espérées par rapport à l’ancien état.

Il peut comporter deux éléments :

• si le commit clôt un ticket, il faut indiquer sur une ligne son numéro de la façon suivante : « Close #58 »
• si le commit entraîne une rupture de compatibilité, il doit comporter une ligne avec la mention « BREAKING CHANGES » en majuscules.