Logs de commits et Changelog #5208

Nous avons introduits un CHANGELOG.md dans SPIP et ses plugins-dist en suivant https://keepachangelog.com/en/1.0.0/ . Cf #5042 et #5121

Actuellement

Pour le moment ce changelog est généré «à la main» en ajoutant une entrée dans les PR
Les reports du Changelog dans les branches (de master à 4.1 par exemple) conflictent du coup (on ne fait pas de release dans master, mais des releases dans la branche 4.1)
Dans master, on retire les lignes qui ont été intégrées dans une release (on a enlevé par exemple là tout ce qui a été releasé dans la 4.1.x) de sorte que le CHANGELOG de master ne montre que changements qui diffèrent de la dernière version stable releasée.

On voit que déjà il y a quelques problématiques (sur les reports, sur master après release) pour gérer le CHANGELOG.

Améliorer les logs de commits

Si on veut pouvoir (re) générer automatiquement un Changelog lors d’une release (plutôt que de le traiter à la main — Keep a Changelog suggère de mettre que les éléments pertinents pourtant), il faut que les logs de commits soient facilement identifiables pour indiquer si cet élément est important à prendre en compte, et à quel endroit dans le changelog.

Mais même, rien que pour la rigeur et la relecture, des bons logs, c’est bien :)

Il existe "Conventional Commits" https://www.conventionalcommits.org/fr/v1.0.0/ pour ça.

Cette nomenclature fonctionne sur la base d’un titre qui identifie le type de commit (fix:, feat: par défaut), où chaque projet définit un peu ses types.

Un article en parle là et propose une liste qui peut se coupler avec Keep a Changelog en partie

https://medium.com/neudesic-innovation/conventional-commits-a-better-way-78d6785c2e08

build: The commit alters the build system or external dependencies of the product (adding, removing, or upgrading dependencies).

change: The commit changes the implementation of an existing feature.

chore: The commit includes a technical or preventative maintenance task that is necessary for managing the product or the repository, but it is not tied to any specific feature or user story. For example, releasing the product can be considered a chore. Regenerating generated code that must be included in the repository could be a chore.

ci: The commit makes changes to continuous integration or continuous delivery scripts or configuration files.

deprecate: The commit deprecates existing functionality, but does not remove it from the product. For example, sometimes older public APIs may get deprecated because newer, more efficient APIs are available. Removing the APIs could break existing integrations so the APIs may be marked as deprecated in order to encourage the integration developers to migrate to the newer APIs while also giving them time before removing older functionality.

docs: The commit adds, updates, or revises documentation that is stored in the repository.

feat: The commit implements a new feature for the application.

fix: The commit fixes a defect in the application.

perf: The commit improves the performance of algorithms or general execution time of the product, but does not fundamentally change an existing feature.

refactor: The commit refactors existing code in the product, but does not alter or change existing behavior in the product.

remove: The commit removes a feature from the product. Typically features are deprecated first for a period of time before being removed. Removing a feature from the product may be considered a breaking change that will require a major version number increment.

revert: The commit reverts one or more commits that were previously included in the product, but were accidentally merged or serious issues were discovered that required their removal from the main branch.

security: The commit improves the security of the product or resolves a security issue that has been reported.

style: The commit updates or reformats the style of the source code, but does not otherwise change the product implementation.

test: The commit enhances, adds to, revised, or otherwise changes the suite of automated tests for the product.

The <type> field can be used with automated tools to automatically generate release notes or update a change log for the product release. If you keep a change log following the Keep a Changelog style, you could map the fields to change log headings like this:

feat → Added

change → Changed

deprecate → Deprecated

remove → Removed

fix → Fixed

security → Security

Remarques

Ce qui est ennuyant me semble t’il est que Conventional Commits place les références extérieures (N° de tickets) dans le footer du message de commit, ce qui fait qu’on ne les voit pas directement sur un git log --oneline ou équivalents

Questions

Est-ce qu’on peut se dire qu’on essaie d’écrire les logs de commits en suivant cette nomenclature ?

Si on a une base de logs comme ça ça pourra permettre de voir si on peut les utiliser ensuite pour générer un changelog pertinent avec des outils adaptés, tel que https://github.com/marcocesarato/php-conventional-changelog

Est-ce qu’on peut se définir éventuellement une liste de scopes ? À quel endroit du logiciel on intervient (mis entre parenthèses après le type) tel que fix(api):

Nous avons introduits un `CHANGELOG.md` dans SPIP et ses plugins-dist en suivant https://keepachangelog.com/en/1.0.0/ . Cf #5042 et #5121 ### Actuellement - Pour le moment ce changelog est généré «à la main» en ajoutant une entrée dans les PR - Les reports du Changelog dans les branches (de master à 4.1 par exemple) conflictent du coup (on ne fait pas de release dans master, mais des releases dans la branche 4.1) - Dans master, on retire les lignes qui ont été intégrées dans une release (on a enlevé par exemple là tout ce qui a été releasé dans la 4.1.x) de sorte que le CHANGELOG de master ne montre que changements qui diffèrent de la dernière version stable releasée. On voit que déjà il y a quelques problématiques (sur les reports, sur master après release) pour gérer le CHANGELOG. ### Améliorer les logs de commits Si on veut pouvoir (re) générer automatiquement un Changelog lors d’une release (plutôt que de le traiter à la main — Keep a Changelog suggère de mettre que les éléments pertinents pourtant), il faut que les logs de commits soient facilement identifiables pour indiquer si cet élément est important à prendre en compte, et à quel endroit dans le changelog. Mais même, rien que pour la rigeur et la relecture, des bons logs, c’est bien :) Il existe "Conventional Commits" https://www.conventionalcommits.org/fr/v1.0.0/ pour ça. Cette nomenclature fonctionne sur la base d’un titre qui identifie le type de commit (`fix:`, `feat:` par défaut), où chaque projet définit un peu ses types. Un article en parle là et propose une liste qui peut se coupler avec Keep a Changelog en partie https://medium.com/neudesic-innovation/conventional-commits-a-better-way-78d6785c2e08 > - `build:` The commit alters the build system or external dependencies of the product (adding, removing, or upgrading dependencies). > - `change:` The commit changes the implementation of an existing feature. > - `chore:` The commit includes a technical or preventative maintenance task that is necessary for managing the product or the repository, but it is not tied to any specific feature or user story. For example, releasing the product can be considered a chore. Regenerating generated code that must be included in the repository could be a chore. > - `ci:` The commit makes changes to continuous integration or continuous delivery scripts or configuration files. > - `deprecate:` The commit deprecates existing functionality, but does not remove it from the product. For example, sometimes older public APIs may get deprecated because newer, more efficient APIs are available. Removing the APIs could break existing integrations so the APIs may be marked as deprecated in order to encourage the integration developers to migrate to the newer APIs while also giving them time before removing older functionality. > - `docs:` The commit adds, updates, or revises documentation that is stored in the repository. > - `feat:` The commit implements a new feature for the application. > - `fix:` The commit fixes a defect in the application. > - `perf:` The commit improves the performance of algorithms or general execution time of the product, but does not fundamentally change an existing feature. > - `refactor`: The commit refactors existing code in the product, but does not alter or change existing behavior in the product. > - `remove:` The commit removes a feature from the product. Typically features are deprecated first for a period of time before being removed. Removing a feature from the product may be considered a breaking change that will require a major version number increment. > - `revert:` The commit reverts one or more commits that were previously included in the product, but were accidentally merged or serious issues were discovered that required their removal from the main branch. > - `security:` The commit improves the security of the product or resolves a security issue that has been reported. > - `style:` The commit updates or reformats the style of the source code, but does not otherwise change the product implementation. > - `test:` The commit enhances, adds to, revised, or otherwise changes the suite of automated tests for the product. > The `<type>` field can be used with automated tools to automatically generate release notes or update a change log for the product release. If you keep a change log following the Keep a Changelog style, you could map the <type> fields to change log headings like this: > > - feat → Added > - change → Changed > - deprecate → Deprecated > - remove → Removed > - fix → Fixed > - security → Security ### Remarques Ce qui est ennuyant me semble t’il est que Conventional Commits place les références extérieures (N° de tickets) dans le footer du message de commit, ce qui fait qu’on ne les voit pas directement sur un `git log --oneline` ou équivalents ### Questions Est-ce qu’on peut se dire qu’on essaie d’écrire les logs de commits en suivant cette nomenclature ? Si on a une base de logs comme ça ça pourra permettre de voir si on peut les utiliser ensuite pour générer un changelog pertinent avec des outils adaptés, tel que https://github.com/marcocesarato/php-conventional-changelog Est-ce qu’on peut se définir éventuellement une liste de `scopes` ? À quel endroit du logiciel on intervient (mis entre parenthèses après le type) tel que `fix(api):`

Super, voilà un début de conf pour php-conventional-changelog pour suivre ces recommandation :

<?php

use ConventionalChangelog\Git\Repository;

return [
  'headerDescription' => 'Changelog de SPIP '. Repository::getCurrentBranch(),
  'preset' => [
    // Types section
    'feat'     => ['label' => 'Added', 'description' => 'New features'],
    'change'   => ['label' => 'Changed', 'description' => 'Changes in existing functionality'],
    'deprec'   => ['label' => 'Deprecated', 'description' => 'Deprecates existing functionality'],
    'remove'   => ['label' => 'Removed', 'description' => 'Removed features'],
    'fix'      => ['label' => 'Fixed', 'description' => 'Bugs and issues resolution'],
    'sec'      => ['label' => 'Security', 'description' => 'Fixed vulnerabilities'],
    'l10n'      => ['label' => 'Localization', 'description' => 'Text transaltion'],
  ],
  'ignoreTypes' => [],
  'ignorePatterns' => ['/^chore\(release\):/i'],
  'changelogVersionFormat' => '## [{{version}}] - {{date}}',
  'disableLinks' => true,
  'hiddenHash' => true,
  'hiddenVersionSeparator' => true,
];

Dans mon cas, j'ai opté pour sec au lieu de security et deprec au lieu de deprecate pour faire plus court, mais on peut s'aligner sur ce que mentionne l'article que tu cites.

En reprenant quelques logs de commits de la 4.1, ça donne le source qui suit visible ici https://rentry.co/2adnu

## [4.1.3] - 2022-06-02

### Fixed

* Login lors de la restauration des cles depuis un compte webmestre #5204
* Lors de la copie locale on appele la sanitisation SVG, qui elle même commence par forcer les unités de la viewbox #5118
* On peut avoir plusieurs adresses courriel de suivi, séparées par des virgules #5190

### Changed

* Améliorer le comportement du bouton 'Ajourd'hui' dans le dateur en surlignant le jour courant + ajout option data-todayhighlight sur les input.date + fix option data-clearbtn #5195

### Security

* Lever le flag `espace_prive=1` quand on calcule un traitement via la balise `#INFO_` dans l'espace prive, pour bien avoir tous les traitements nécéssaires

Je proposerais bien une version plus court pour remove => rem ou del.

Plutôt partisan, après je me posais la question de la compatibilité avec d'autres automatismes attendus, notamment ce qui est reconnu par toutes les forges (Gitea et autres). Non seulement eux mettent la référence à la fin, mais même si on mettait dans la parenthèse, ça ne correspondrait pas aux fix #123 reconnus qui permet d'interragir auto sur des tickets depuis les logs.

Après au pire on le met en double, un peu dommage mais ça marcherait…

Fix(truc): description bla bla fix #123

Après au pire on le met en double, un peu dommage mais ça marcherait…

Pas besoin de le mettre en double, car comme je le disais sur IRC, l'écriture fix(#XXX): n'est pas "valide" et n'est pas prise en charge par l'outil php-conventional-changelog. Un log "correct" serait de la forme :

fix: On peut avoir plusieurs adresses courriel de suivi, séparées par des virgules
    
L'adresse de suivi peut être une série d'adresses séparées par des virgules.
    
Par conséquent :
- l'expliciter dans la chaîne de langue
- avoir un input de type `text` et pas `email` sinon les navigateurs
bloquent les virgules.
    
Fix: #5190

bé oui ya bien deux fois le mot-clé Fix, c'est ce que je disais :)
On peut pas mettre la ref au même endroit que le mot-clé du début quoi, donc faut le remettre ailleurs dans le log (sans les : je crois pour les forges, ou bien ça gère plusieurs écritures mais peu importe ça). Donc bon oui c'est pas très grave, on le met deux fois

Oui ça fait deux fois Fix, mais le type du commit ne sert pas à ça, et quand c'est un commit qui apporte un changement par exemple, ya plus doublon :p

change: Améliorer le comportement du bouton 'Ajourd'hui' dans le dateur en surlignant le jour courant + ajout option data-todayhighlight sur les input.date + fix option data-clearbtn
    
Fix: #5195

PS : Fix: est pris en charge par github d'après l'article cité par @marcimat donc je pense que gitea en fait de même (enfin j'espère ^^).

Ceci étant dit je trouve ennuyant de pas voir le ticket directement dans un git lg (mais c’est peut être juste moi).

Même si feat est un raccourci, comme perf je suis plutôt pour ne pas s’éloigner de ce que proposent «les autres» sur les différents types, et donc si on doit pouvoir indiquer Deprecated, Removed et Security, alors autant prendre ce que propose l’article de Medium (mais c’est le seul endroit où ça en cause), par exemple chez Angular (https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit), ça irait semble t’il dans refactor ou fix pour ces cas.

Notons que Gitlab utilise un autre trick https://docs.gitlab.com/ee/development/changelog.html en ne reportant dans le changelog que les commits qui ont un tag Changelog: <type> dans le footer

Très bonne idée.

Du moment qu'il y a une recette facile à suivre et bien documentée, on suivra :)

Ma seule remarque, comme suggéré par @marcimat, si on peut éviter les petites exceptions "à la spip" et pas trop s'éloigner de ce que font «les autres», ça sera plus facile à retenir.

Ça discute les motclés retenus et leur traitement, mais quelle est l'interface pour le dev = quelle apparence au final doit prendre un log de commit ?
Un exemple rendrait ça plus clair.

Ça discute les motclés retenus et leur traitement, mais quelle est l'interface pour le dev = quelle apparence au final doit prendre un log de commit ?
Un exemple rendrait ça plus clair.

"Au hasard" parmi cette liste https://git.spip.net/spip/spip/commits/branch/master :

fd36a8dacb
2f20ecd7a3

Tiens là https://github.com/fteem/git-semantic-commits je vois que y a aussi "localize:" ça pourrait être bien pour salvatore aussi, et certains de nos commits…

Tiens là https://github.com/fteem/git-semantic-commits je vois que y a aussi "localize:" ça pourrait être bien pour salvatore aussi, et certains de nos commits…

Ha oui bonne idée, mais pour faire plus court i18n serait peut-être plus adapté ?

i18n ou l10n ?

/mode troll on

Ha mais oui l10n carrément !

=> https://fr.wikipedia.org/wiki/Internationalisation_et_localisation

Pour mémoire, je découvre https://scriv.readthedocs.io/en/latest/philosophy.html

L'outil est en python, donc pas forcément intéressant pour nous, mais le principe l'est : chaque entrée de changelog est stockée dans un fichier d'un répertoire dédié, et on peut lancer la génération du changlog à partir de ces fichiers. Ça permet d'éviter les soucis de conflit sur le changelog.

J'ai trouvé des outils en php qui fonctionnent sur le même principe :

https://packagist.org/packages/automattic/jetpack-changelogger qui permet de générer des changelogs au format keepachangelog
https://packagist.org/packages/markwalet/laravel-changelog

En regardant comment fonctionne https://packagist.org/packages/automattic/jetpack-changelogger on a découvert avec @b_b qu’on n’écrivait pas totalement comme il fallait les changelog de SPIP suivant Keep a Changelog.

Effectivement les titres sont de ce type

## [x.y.z] - YYYY-MM-DD

Mais les crochets, en fait renvoient à une note en markdown, et je n’avais pas fait attention (je ne connaissais pas cette écriture markdown en fait). En pied de fichier, il devrait y avoir

[x.y.z]: une URL vers le diff ou le tag

Ou alors on devrait écrire (sans lien)

## x.y.z - YYYY-MM-DD

Je pense qu'on peut se simplifier la vie et se passer du lien.

En lien avec https://discuter.spip.net/t/proposition-devolution-des-regles-de-contribution/161362/6

Maintenant que c'est dans nos règles de contribution https://www.spip.net/fr_article825.html#Regles-de-contribution on peut fermer le ticket ?

À moins qu'on le garde sous le coude pour avancer sur la question de jetpack-changelogger et cie ?

À moins qu'on le garde sous le coude pour avancer sur la question de jetpack-changelogger et cie ?

j'aurais tendance à en faire un autre, pour avoir un historique clean.

La suite par là #5524 et on ferme ici.