Skip to content

Logs de commits et Changelog

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

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):

Forge communautaire SPIP | Charte d'utilisation | Signaler un problème sur ce site