Journal Changelog, pour quoi, pour quoi ?

Posté par  (site web personnel) . Licence CC By‑SA.
Étiquettes :
18
5
fév.
2023

Demat'iNal,

À quelques jours / semaines d'intervalles, j'ai eu besoin d'intéragir avec la notion de Changelog, ou plutôt de release note, mais je vais abusivement utiliser le premier terme pour désigner le second.

  1. Un utilisateur de la bibliothèque de types vectoriels xsimd nous a demandé d'en fournir un (ce que j'ai fait assez diligeamment)

  2. Lors d'une chouette présentation au FOSDEM hier, dans la devroom LLVM, quand j'ai appris que le Changelog n'était pas utilisé par les personnes faisant une mise à jour de version majeur de LLVM pour une base de code basée sur ce dernier

  3. Lors de la sortie de pythran 0.12.1, biñs pour laquelle j'ai écrit un Changelog comme à l'accoutumé.

Mon approche personelle de l'écriture d'un changelog ne casse pas trois pattes à un canard boiteux : git log tag-de-debut..tag-de-fin dont je fais un pot pourri des titres, avec un petit tri / filtre suivant le ressenti.

Pour LLVM, l'approche est plus formalisée : tout commit introduisant un changement visible par l'utilisateur (nouveaux drapeaux de compilation, amélioration du support d'un langage etc) se doit de mettre à jour un document qui sera utilisé lors de la release pour… documenter les changements majeurs.

À titre personnel, j'éprouve une certaine satisfaction à écrire ces notes de release : c'est un moment où l'on tourne un peu la tête vers le passé, ce qui a été accompli, les avancées du projet… c'est aussi un moment où l'on se réjoui des contributions faites et reçues, bref c'est la fête.

Par contre en tant qu'utilisateur et packageur, je les utilise rarement. Pas jamais, typiquement j'aime bien lire celles de GCC, mais sorti de ça…

Bref, je suis curieux de tes retours sur ce sujet discret et anodin ?

  • # Retours

    Posté par  (site web personnel) . Évalué à 10.

    • en tant que membre de l’équipe LinuxFr.org : le code en lui-même n’est pas versionné (autrement qu’être une succession de commits datés), ils sont annoncés dans les rétrospectives de la quinzaine mais sans effort particulier de vulgarisation, et parfois une dépêche vient décrire les nouveautés (il y en a une en rédaction par exemple).
    • en tant que développeur, sur du code partagé mis à la disposition d’autres personnes (par exemple des rôles ansible communautaires) : quasi chaque commit donne lieu à une version, et donc je décris à chaque fois le changement (et l’étiquette x.y.z sur le commit permet aussi de savoir à quel point on a cassé la rétrocompatibilité). Mais je ne m’astreins pas à avoir en plus un fichier Changelog dans le dépôt.
    • en tant que admin sys, avant de faire des mises à jour liées à du fonctionnel (ie. pas juste des mises à jour de sécurité, confiées aux équipes de la distribution par exemple), alors je parcours les notes de version notamment pour voir des ruptures de compatibilité éventuelles, ou des annonces de fonctions obsolètes ou en voie de l’être, ou des changements de configuration, ou même des nouvelles fonctionnalités qui pourraient m’intéresser. Souvent une lecture rapide en diagonale, parce que toute façon il est peu probable que je comprenne chaque ligne individuellement, sauf à connaître sur le bout des doigts le logiciel en question, et encore…
    • en tant que simple utilisateur : ça dépend, je lis les notes de versions pour les montées de distribution Debian par exemple, j’essaie de lire les notes de versions de chaque application sur mobile (mais souvent c’est plus que sommaire « on a corrigé des trucs » et « on a amélioré les perfs ») mais c’est tellement fréquent…

  • # dans le projet Koha

    Posté par  (site web personnel, Mastodon) . Évalué à 4.

    Dans le projet Koha (koha-community.org), nous avons développé un script qui génère les release note automatiquement. Il prend les messages de commit et, si le commit est rattaché à un bug (bugs.koha-community.org) pour lequel quelqu'un a saisi le champ "release note description"), on l'utilise.

    Ca génère ça : https://koha-community.org/koha-22-11-released/
    le script est là : https://git.koha-community.org/Koha-community/release-tools

    Si ça peut servir à quelqu'un, j'en serai ravi

    • [^] # Re: dans le projet Koha

      Posté par  (site web personnel) . Évalué à 2.

      Merci pour le partage ! C'est sympa l'idée de filtrer les commit suivant le bug id, et de les classifier en se basant sur les infos du bug.

      Par contre ça fait d'énorme changelog. Ce n'est pas un mal hein, probablement un choix. On pourrait imaginer (je n'ai pas regardé si votre gestionnaire de bug permet de hiérarchiser ces derniers) de n'afficher que les bugs d'une certaine criticité… Merci en tout cas \o

  • # un retour de loup solitaire

    Posté par  . Évalué à 4. Dernière modification le 05 février 2023 à 23:25.

    Peut-être un peu comme Benoît ci-dessus.

    • Je parcours ceux de KDE pour me faire une idée des changements, plus sérieuse que les copies d'écran tape à l'oeil des annonces de sortie ; je les parcours aussi pour vérifier qu'un projet est super actif ou continue la chasse aux bugs (Kate et les KIO pour rester dans KDE par exemple).
    • J'y farfouille avant de rapporter un bugs
    • Je les lis sans rien comprendre, en me disant que ça avance ça avance, trop frustré par le laconisme des développeurs consciencieux qui laissent passer des années entre les nouvelles versions salivantes (par exemple chez Haïku)!
    • Je les remplis avec excès pour me dire que j'ai fait plein de trucs, c'est dur le travail solitaire.
    • Sous ma casquette de sysadmin je lis certains changelogs de paquets, mais je ne suis pas assidu.

  • # Dopamine, mais je me désintox.

    Posté par  . Évalué à 7.

    Le changelog, c'est un peu mon shot de dopamine à moi. Façon « Tiens, un truc nouveau » pour les consommateurs de grande surface.

    Alors oui, quand y a écrit « Correction d'un dépassement de mémoire lors d'un appel à fonction_mega_rare à l'aide de données mal formées », c'est pas super utile.

    Par contre, pour les auteurs de bibliothèques : c'est inestimable. Je co-maintiens IHateMoney en Python, et quand dependabot ouvre une modif pour faire une montée en version des nombreuses bibliothèques, je suis bien content de pas avoir à chercher ce qui pourrait péter avant que ça pète réellement.

Suivre le flux des commentaires

Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.