Outils de changelog

Je ne sais plus trop où on en était du recensement des outils de changelog.

Et je ne suis pas certain qu’on était toustes en phase sur quoi en faire.

Perso, quand j’utilise un tel outil, c’est pour mettre à jour un fichier « technique » CHANGELOG.md au moment d’une release : ça rassemble les commits, ça les classe, ça update le fichier dans le dépôt git et zou, y a plus qu’à tagguer.

Avantage : personne ne touche au fichier proprement dit pendant les phases de dev.
Inconvénients : faut que les messages de commits respectent une convention assez stricte, voire, que les devs maîtrisent le rebase pour le reword, le squash, etc.

Perso, ça m’irait comme ça … mais … j’imagine que ça va faire débat …

Parfois pour résoudre un ticket complexe, il y a besoin de plusieurs commits (parfois plein), volontairement découpés pour bien voir les différentes étapes des choses qu’il y a eu à faire. Du coup si ya 3, 5, 10 commits qui résolvent le ticket 123, comment ça marche pour savoir quoi mettre dans le changelog ? Dans lequel généralement on veut une seule ligne, avec le numéro du ticket et une phrase très résumée de ce qu’on a résolu.

Du coup, dans la majorité des cas il y a une PR, est-ce que c’est pas plutôt (dans ces cas là) les PR qui doivent être compilées dans le changelog, plutôt que les commits, fussent-ils méga formatés ?

1 « J'aime »

effectivement on pourrait imaginer un hook de post merge qui recompile les choses.

Bonnes questions :slight_smile: , beaucoup de réponses possibles.

Peu d’outils génériques « comprennent » les intentions des devs à travers la multiplicité des commits, surtout que, oui, ce que tu décrits arrive souvent.

Heureusement, on peut (et je dirais même qu’on doit), retoucher le fichier mis à jour avant de faire le tag (que ce soit en local avant le git push ou, a posteriori, avant le tag de release.

C’est un job. :slight_smile:

Ça, c’est la cerise sur le gâteau. Faut faire le gâteau d’abord :wink:

Pour rappel Faciliter les modifications des fichiers Changelog (#5524) · Tickets · spip / spip · GitLab :slight_smile:

1 « J'aime »

Merci, je ne savais plus où c’était… :kissing:

J’ai regardé un peu ce qui peut se faire avec GitLab lui-même.

On peut faire des releases avec, sans passer par git ou un outil PHP supplémentaire à intégrer comme dépendance de dev dans le code.
Et dans ce cadre, générer un changelog.

On peut créer une « release » manuellement (on pouvait aussi le faire avec gitea, c’est aussi possible avec github.com)
C’est lié à un tag et cela permet d’associer des « artefacts » à un tag. Ces artefacts sont des fichiers. ça peut être des zips, des .md, ou toutes autres choses …

Je résume :

Suite à la création d’un tag, on peut déclencher un job de CI spécifique pour le dépôt spip/spip qui peut :

  1. Produire le zip SPIP
  2. Générer le changelog
  3. En faire des artefacts associés au tag qui vient d’être créé.

Cela permet, entre autre, d’automatiser et de stocker le zip de chaque version de SPIP (stable ou alpha, etc.). On n’aurait plus besoin de files.spip.net pour ça. Les urls de ces éventuels zips étant prédictibles (et récupérables via l’API de GitLab), il serait assez simple d’adapter spip_loader.
Le changelog étant généré automatiquement (en markdown), avec un URL tout aussi prédictible, Il serait aussi possible de le récupérer pour générer l’article de release sur le blog. (Cf. Fluidifier la création de releases - #58 par JamesRezo)
L’outil qui génère ce type de changelog est paramétrable mais demande une certaine rigueur dans les messages de commits… c’est une contrainte dont il faudra discuter si on s’intéresse à cette méthode …

C’est une alternative aux outils proposés dans le ticket ci-dessus … ça n’annule pas leur inspection, tests, etc.

2 « J'aime »

C’est ce qui amha deviendra le « nouveau point de friction » (qui actuellement est l’ajout des entrées dans les fichiers de changelog).

Tu as une ou plusieurs piste pour l’outil de génération de changelog ? Tu peux partager les liens stp, histoire qu’on regarde ce que ça génère comme contenu.

Merci pour la relance sur le sujet, ça ne fera pas de mal d’automatiser encore plus les releases et surtout d’avancer sur ce « problème d’adaptation des usages » du aux changelogs.

Y a plusieurs points d’entrée :

Beaucoup de lectures … :slight_smile:

Super, merci pour les liens, j’en retiens donc essentiellement « the GitLab Changelog API » Changelogs | GitLab, ça permet de se passer de la lecture de la partie « chatbot », « blockchain » et « capital venture » du tuto gitlab, qui reste intéressant si on passe ces références vendeuses ^^

En résumé, ça permet de générer le changelog à partir d’un « trailer » (un marqueur spécifique dans le commit, comme pour les commits conventionnels) posé dans le log d’un commit, exemple « Changelog: feature ».

To be included in a changelog, a commit must contain a specific Git trailer.

Donc un commit qui ne contient pas de marqueur ne sera pas listé dans le changelog. Ainsi, sur une PR qui contient plusieurs commits, on peut définir son changelog uniquement dans le commit « révélateur » de la PR.

On peut aussi personnaliser les catégories utilisé dans les marqueurs pour les ligner sur celles qu’on utilisent avec les commits conventionnels cf Changelogs | GitLab

Et aussi personnaliser le format du changelog généré, bref ça semble vraiment une piste intéressante, car ça nous évitera les conflits sur les modifications des fichiers changelog lors des reports dans les branches stables. Et, si jamais on doit reprendre le changelog foireux d’une PR avant merge, il suffit d’un git commit --amend.

Le seul point qui me semble moins pratique que l’usage actuel est que je ne pense pas qu’on puisse revenir sur une entrée de changelog une fois le commit mergé dans une branche (on ne fais pas de commit amend et force push dans master ou une branche stable).

À noter, dans le tuto les gens utilisent des commits de merge sur chaque PR, et donc c’est avec ce commit que le changelog est posé, or on n’utilise pas les commits de merge chez nous.

Je suis bien intéressé pour tester le bouzin sur la partie changelog, je tente de trouver un temps pour ça dans un repo perso dans les jours à venir (si personne ne s’y colle avant).

1 « J'aime »

J’ai commencé, dans mon coin, là où il y a une CI, sur la production de zip, mais à un rythme pépère…
J’y retourne après le chantier du dossier prive/

Bonjour,

De mon côté, je teste git Cliff avec SoyezCréateurs.
Et ce dernier permet de générer automatiquement le n° de version : Bump version | git-cliff

How it works is that for a semantic versioning such as <MAJOR>.<MINOR>.<PATCH>:

  • « fix: » → increments PATCH
  • « feat: » → increments MINOR
  • « scope! » (breaking changes) → increments MAJOR

Et en plus on peut générer le contenu du changelog à n’importe quel moment en jouant avec l’API de Gitlab Repositories API | GitLab !

1 « J'aime »

Et du coup, plus besoin d’exiger son édition dans les PRs : CQFD :slight_smile:

par contre ca veut dire être encore plus rigoureux sur les messages de commits, car on ne peut plus revenir en arrière ? ou alors le changelog généré peut quand meême être corrigée manuellement?

1 « J'aime »

Les deux mon capitaine ! :heart:

Le tout étant de savoir quel soutien on souhaite apporter aux 2/3 personnes qui font les releases ^^

  • On peut éditer les messages de commits avant de générer le changelog (merci les amis …)
  • On peut refuser les PRs avec des messages de commit dégeu (on est des ordures)
  • On peut bricoler le changeog avant de le pousser sur le serveur (merci encore pour votre participation)
  • Le jour où on a une CI, on teste « la qualité » des messages de commit et un robot fait des suggestions …
  • Etc.
1 « J'aime »

Je rappelle aussi qu’une release peut prendre entre 2 heures et une journée entière. Des fois ça demande une nouvelle release rapprochée …

C’est un métier-passion …

Et on peut aussi ajouter :

  • il y aurait le changelog généré automatiquement pour les releases d’un point de vue gitlab Releases | GitLab
  • et toujours la possibilité de générer le fichier CHANGELOG.md dans le repo, mais à partir des commits en jouant avec l’API, ce qui permet de revenir sur les coquilles après coup
1 « J'aime »