Le changelog.md généré n’est pas au format markdown… #5121

Ça s’affiche mal : il faut générer une autre écriture plus conforme.

https://git.spip.net/spip/spip/src/branch/4.1/CHANGELOG.md

https://keepachangelog.com/fr/1.0.0/ par ailleurs est de très bon conseil.

Cela dit pas facile de tenir un changelog actuellement qui ne soit pas une liste moche de commits.

Ou il faut s’y tenir directement en créant un CHANGELOG.md dans chaque master, reporter chaque élément après "unreleased" dans les branches concernées éventuellement.

L’avantage est que ça peut faciliter ensuite la création de l’article de blog d’une sortie…

Ça voudrait dire aussi ne plus mettre le changelog de chaque plugin-dist dans celui du core pour que chaque projet gère le sien.

Dans un tout premier temps on pourrait utiliser quelque chose comme ça :

# Changelog

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)

## [Unreleased]

## [4.0.1] - 2022-04-01

### SPIP

#### Changed

- Report chaines de langues (Salvatore)
- Ticket #5109 : Il est recommandé de mettre les fichiers cachés en 404 (via le htaccess)
#### Fixed

- Ticket #5109 : bloquer l’accès aux fichiers de définition Composer (via le htaccess)
- Coquille dans _SPIP_VERSION_ID Nous sommes en version 4.1 ici, pas 41…
- Éviter des deprecated (null sur str*) lors de l’utilisation de `#CHEMIN{#ENV{absent}}`

### Archiviste

#### Fixed

- Fonctionnement avec une extension zip récente compilée avec une vieille version de libzip-dev
- Tests unitaires depuis la suite de tests Spip.

### Forum

#### Fixed

- Les #NOTES doivent aussi passer par texte_backend et liens_absolus - fixes #4755

### Medias

#### Fixed

- Ticket #4857 (suite) : correction du nom de constante `_IMAGE_TAILLE_MINI_AUTOLIEN`

Il y a :

un intertitre en plus par rapport à keep a changelog (Spip, Archiviste, ...)
pas de version sur les plugins-dist

Il y a plusieurs problèmes, et à mon avis ça ne va pas à terme.

Bon, déjà je ne sais pas le générer automatiquement (il faut que je reprenne mes outils de génération de release pour adapter, et ça fait une passe manuelle facheuse forcément)
Effectivement ce changelog ne devrait concerner que ce projet spip/spip et pas les plugins-dist qui devraient donc eux aussi avoir leurs CHANGELOG.md
On peut surveiller facilement les releases de SPIP, mais les tags posés sur les plugins-dist sont plus fréquents et risquent, si le changelog est manuel de ne pas être renseigné correctement, d’autant plus entre le master et les branches respectives…

Pour releaser, je pourrais forcer de vérifier que la version en cours du plugin dist a bien un changelog pour elle (ça risque d’être cocasse), et en même temps est-ce vraiment à mon script de release de s’en occuper… parce que bon… ça serait mieux que le changelog soit géré directement proprement dans chaque plugin.

Mais bon, par exemple faire un report de chaine de langue (avec mes outils de release) va devoir faire créer un nouveau tag + version au plugin concerné, même si aucun autre changement n’a eu lieu (ce qui reste logique) : mais du coup il faudrait une entrée de changelog (donc éditer le fichier plus ou moins à la main je présume) et c’est donc du temps à passer.

Mais c’est aussi du temps qui simplifie grandement je pense l’écriture du billet de blog ensuite (il suffit de récolter les différents changelog qui sont déjà humainement écrits)

A priori il «suffit» de conserver dans CHANGELOG.md le changelog de X.0.0 (le dernier X), et de n’avoir les X-1 que dans les branches correspondantes (si le changelog devient trop long notamment)

Dans un tout premier temps on pourrait utiliser quelque chose comme ça : ```md # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) ## [Unreleased] ## [4.0.1] - 2022-04-01 ### SPIP #### Changed - Report chaines de langues (Salvatore) - Ticket #5109 : Il est recommandé de mettre les fichiers cachés en 404 (via le htaccess) #### Fixed - Ticket #5109 : bloquer l’accès aux fichiers de définition Composer (via le htaccess) - Coquille dans _SPIP_VERSION_ID Nous sommes en version 4.1 ici, pas 41… - Éviter des deprecated (null sur str*) lors de l’utilisation de `#CHEMIN{#ENV{absent}}` ### Archiviste #### Fixed - Fonctionnement avec une extension zip récente compilée avec une vieille version de libzip-dev - Tests unitaires depuis la suite de tests Spip. ### Forum #### Fixed - Les #NOTES doivent aussi passer par texte_backend et liens_absolus - fixes #4755 ### Medias #### Fixed - Ticket #4857 (suite) : correction du nom de constante `_IMAGE_TAILLE_MINI_AUTOLIEN` ``` Il y a : - un intertitre en plus par rapport à keep a changelog (Spip, Archiviste, ...) - pas de version sur les plugins-dist ---- Il y a plusieurs problèmes, et à mon avis ça ne va pas à terme. 1) Bon, déjà je ne sais pas le générer automatiquement (il faut que je reprenne mes outils de génération de release pour adapter, et ça fait une passe manuelle facheuse forcément) 2) Effectivement ce changelog ne devrait concerner que ce projet spip/spip et pas les plugins-dist qui devraient donc eux aussi avoir leurs CHANGELOG.md 3) On peut surveiller facilement les releases de SPIP, mais les tags posés sur les plugins-dist sont plus fréquents et risquent, si le changelog est manuel de ne pas être renseigné correctement, d’autant plus entre le master et les branches respectives… Pour releaser, je pourrais forcer de vérifier que la version en cours du plugin dist a bien un changelog pour elle (ça risque d’être cocasse), et en même temps est-ce vraiment à mon script de release de s’en occuper… parce que bon… ça serait mieux que le changelog soit géré directement proprement dans chaque plugin. Mais bon, par exemple faire un report de chaine de langue (avec mes outils de release) va devoir faire créer un nouveau tag + version au plugin concerné, même si aucun autre changement n’a eu lieu (ce qui reste logique) : mais du coup il faudrait une entrée de changelog (donc éditer le fichier plus ou moins à la main je présume) et c’est donc du temps à passer. Mais c’est aussi du temps qui simplifie grandement je pense l’écriture du billet de blog ensuite (il suffit de récolter les différents changelog qui sont déjà humainement écrits) ---- A priori il «suffit» de conserver dans CHANGELOG.md le changelog de X.0.0 (le dernier X), et de n’avoir les X-1 que dans les branches correspondantes (si le changelog devient trop long notamment)

Dans ta proposition je suppose qu'il faudrait ajouter l'id du commit

bah justement si tu as lu https://keepachangelog.com/fr/1.0.0/ ça indique en gros (et plusieurs fois) "Ne laissez pas vos amis utiliser les logs git comme changelogs"

Une entrée de log de changelog peut d’ailleurs concerner plusieurs commits

Mais également surtout ça me semble encore plus compliqué pour des PR : car la PR qui viserait à corriger un truc devrait à la fois corriger le truc, et ajouter l’entrée de changelog (dont elle ne connait pas le hash de commit — ou alors à faire 2 commits séparés peut être)

Autant je trouve intéressant de citer les numéros de tickets #5121 s’il y en a, autant le hash de commit… bon… d’autant que c’est pas le même hash lorsqu’on cherry-pick pour une autre branche… il faudrait donc éditer encore le changelog… pff

Ie: ce n’est pas parce que c’était comme ça avant qu’il faut refaire pareil quitte à changer :)

Avec deux lignes de plus en tête de la liste ça affiche bien un tableau ici même si ça ne répond pas à la question de fond (sur laquelle je reviendrai dès que possible).

commit	qui	quand	quoi
`77b30f66d`	marcimat	2022-04-01	Coquille dans _SPIP_VERSION_ID Nous sommes en version 4.1 ici, pas 41…

Je pige pas. Les explications fournies dans le .md ne sont jamais aussi complètes et précises que la visu du commit concerné. Les explications du .md sont surtout une information générale et une invitation à aller voir ce qui a été fait précisément dans le code, si on est intéressé. Or il n'y a pas toujours de PR ou de tickets indiqués (même si ce serait bien). Et si ni le commit ni la PR ni le ticket ne sont indiqué, ça devient la course au trésor pour trouver le changement de code...

Disons le autrement : l’énergie qu’on déploierait (nous dévs, a priori ça ne sera personne d’autre) à écrire un changelog exhaustif avec les sha de commit, qui ne soit pas la même liste que le git log (que ça on sait générer automatiquement forcément !) en vaut il le coup vraiment… alors que tu peux bien tout autant lire le git log justement (sans avoir besoin de les mettre dans un fichier de changelog par ailleurs)…

On peut aussi regarder chez nos amis (WP, Drupal, Prestashop, n’en ont pas dans leur repo principal)

Une bonne partie semble passer par des tickets.

OK, ça je pige bien :-)

Et dans les exemples le ticket est toujours associés, or le ticket fournit tout ce qu'il faut pour accéder au détail.

Dans spip toutefois ya pas toujours un ticket alors le commit est requis pour approfondir dans ces cas là. Du coup il serait possible de copier le git log concerné dans un fichier texte et simplement intégrer au releaselog.md un lien (unique pour tout le .md) vers ce fichier ? ou ajouter le git log en complément à la fin.

Bonne idée, à documenter dans la foulée.

Ça me semble aussi être une bonne pratique à encourager pour les plugins de la communauté, quand on fait des ajouts fonctionnels mais qu'on n'a pas les droits d'édition sur l'article de documentation, il faut parfois un certain temps avant que ça finisse dedans.

À terme si le format le permet, ça pourrait même permettre d'afficher les derniers changements directement dans svp non ?

Ça me semble aussi être une bonne pratique à encourager pour les plugins de la communauté, quand on fait des ajouts fonctionnels mais qu'on n'a pas les droits d'édition sur l'article de documentation, il faut parfois un certain temps avant que ça finisse dedans.

Concernant la documentation, je crois sincèrement qu'une autre bonne pratique serait d'avoir un README.md pour chaque dépôt. Mais c'est un autre débat ^^

Pour le readme, oui, aussi.
La proposition initiale était de l'afficher sur contrib mais uniquement en fallback, en absence d'article SPIP.
Mais à discuter dans un autre ticket :)

Cf #5042 pour le Readme.

Et oui je pense qu’il faut indiquer un kit de bonne pratique et surtout montrer l’exemple sur les plugins-dist.

Ça vaut donc pour le Readme, changelog, license, (et peut être d’autres plus techniques .editorconfig, ...)

On peut fermer celui là, c’est intégré.