Ajoute un fichier CHANGELOG.md

[Allan-CodeWorks]

Description

De l'avis de différentes personnes de la communauté, la mise en place d'un journal des changements apportés par les différentes release sur openfisca-france-local serait bénéfique.

Avec la suggestion de @MattiSG, voici une proposition de mise en œuvre mêlant ce qui se fait déjà sur openfisca-france et de la standardisation inspirée de common changelog.

Implantation

L'idée générale est de prendre la structure proposée par common changelog et d'y intégrer les éléments pertinents pour parler des évolutions liées au système socio-fiscale sur openfisca-france-local.

Concrètement on se retrouve avec :

1 - le Header Common Changelog personnalisé

Initialement ## <version> - <date> Si on suit les règles de Common Changelog.
Je propose d'y ajouter la référence de la PR (Comme ce qui se fait dans openfisca-france).
En effet, Common Changelog semble s'adapter à des projets avec des releases conséquentes, rassemblant plusieurs PR et donc les références sont précisés à chaques changements.
Chez nous, en écrasante majorité, une PR == une release

2 - Optionel La notice Common Changelog

La notice est optionelle est vient remplir plusieurs fonctions.
Il arrive que la release en question necessite une lecture particulière, détaillée à un autre endroit (issues, conversations, poste de blog ou encore un fichier UPGRADING.md dont nous n'avons pas encore besoin).
La notice permet de renvoyer le lecteur vers ces informations essentielles.

Elle peut aussi permettre de clarifier une information essentielle, sans faire référence à un document externe.

Vous pouvez voir un exemple pour la version 6.0.0.

C'est un paragraphe d'une seule phrase, en italique

3 - La qualification des changements d'openfisca-france

Les releases dans le changelog d'openfisca-france commencent par 4 informations :

- Évolution du système socio-fiscal. | Amélioration technique. | Correction d'un crash. | Changement mineur.
- Périodes concernées : toutes. | jusqu'au JJ/MM/AAAA. | à partir du JJ/MM/AAAA.
- Zones impactées : chemin/vers/le/fichier/contenant/les/variables/impactées.
- Détails

Les deux premières me semblent indispensables pour une meilleure compréhension des implications par les profils moins techniques.

Zones impactées apporte une synthèse précises des fichiers touchés, je me suis dit que c'était également utile même si dispensable. Qu'en pensez-vous ?

Détails Cette partie est équivalente aux Change groups de common-changelog. Je propose donc de ne pas l'inclure mais d'utiliser la syntaxe des change groups que je détaille dans la partie suivante.

4 - Les changements (Change groups de common-changelog)

L'idée de Common changelog est de présenter les changements par catégories distinctes.
Il existe 4 catégories:

- Changed - for changes in existing functionality
- Added - for new functionality
- Removed - for removed functionality
- Fixed - for bug fixes.

Par cohérence avec le reste du projet, je propose de les traduire:

- Changé.es - pour les changements apportés à des fonctionnalités existantes.
- Ajouté.es - Pour les ajouts de nouvelles fonctionnalités
- Retiré.es - Pour le retrait de fonctionnalités
- Corrigé.es - Pour la correction de problèmes

-> Merci de me faire des retours là-dessus.

On présente les catégorie avec un titre Markdown de 3ième niveau, et on liste les modifications. Exemple :

### Changé

- Met à jour le SMIC avec les valeurs de 2023
- ...
- ...

Les modifications sont triées : D'abord les breaking changes puis par ordre d'importance.

Détails :

Les préfixes :

Comme dans le changelog de la version 6.0.0 proposée ici, on peut voir le préfixe breaking qui va mettre en avant un changement particulier, ici changement qui entraine une incompatibilité avec les versions antérieures.
C'est le préfixe qui me semble le plus utile, mais Common Changelog documente aussi d'autres utilités ici

Les releases github :

Common changelog recommande de créer des tags pour chaque version et de lié ce tag à une release reprenant le contenu du changelog. Ceci me semble pertinent, à voir là mise en pratique (piste dans la section automatisation juste après.

L'automatisation :

• Il me semble intéressant de reprendre la vérification faite par la CI sur openfisca-france qui a pour but de vérifier si le changelog à bien été modifié avant d'accepter la PR.

• Pour la publication des releases, Common CHangelog aborde le sujet de l'automatisation de la chose dans sa documentation. Il est mentionné l'utilisation d'une action github facilitant la chose mais elle n'est pas publiée par github.
  -> Qu´en pensez-vous ?

Conclusion :

Le but est d'itérer sur cette proposition pour arriver au résultat le plus utile et le moins contraignant possible.

Tout est sujet à discussion, vos avis sont bienvenus.
J'attire cependant votre attention et sollicite vos retours sur les points suivants :

• Les éléments du changelog d'openfisca-france à garde et notamment Détails
• La traduction des "changements", faut-il traduire  ? est-ce ma proposition semble acceptable?
• L'automatisation des releases github va une action publiée par la communauté

[robinguill]

Le format jumelé entre ce qu'on a sur openfisca-france et le 'Common Changelog' me semble un bon compromis, à éprouver sur la longueur 👍
Pour les zones impactées, c'est peut être utile, côté dev PNDS on s'en sert pour savoir si une release impacte nos aides calculées ou non. Donc pourquoi ne pas le reprendre.
Concernant les noms de catégories traduits, dans le contexte openfisca-france(-local), ça ne me dérange pas.

[Allan-CodeWorks]

Je mets l'automatisation de publication de release Github de côté pour le moment.
J'ai initié un travail sur la branche github_release_automation qui envoi une requête POST avec un JSON que Github indique comme étant invalide.

Le débug me prend trop de temps pour la valeur ajoutée.

[MattiSG]

Bravo @Allan-CodeWorks pour la qualité de cette proposition 👏

Je trouve l'idée très pertinente, et inspirante pour une intégration a posteriori dans les autres modèles OpenFisca !

De manière générale, mon point de vue est qu'il serait préférable de respecter Common Changelog en tant que standard plus que de le voir comme une source d'inspiration, afin de pouvoir bénéficier de l'écosystème d'outils qui s'appuient sur Common Changelog pour, par exemple, extraire des métadonnées, ou générer un Changelog. Quelques retours détaillés ci-dessous pour se rapprocher de cet objectif 🙂

1 - le Header Common Changelog personnalisé

Je suis bien d'accord avec « une PR = une release » (c'est le principe du GitHub Flow volontairement mis en place).
Plutôt que de modifier le header, qui est une partie importante du standard, je propose d'adopter la convention mise en place par Open Terms Archive :

Since each release is produced automatically from a single pull request, the notice is always used to link to the source pull request rather than references, which would always reference the same pull request. References can instead link to relevant specific parts of an RFC, decision record or diff.

Cela donne ceci par exemple :

0.30.0 - 2023-07-10

Full changeset and discussions: #1015.

Added

• Embed Swagger UI for graphical user interface documentation of the API; access it on /docs

On notera la notice standardisée qui se répète pour chaque version publiée, avec une référence unique vers une PR, mais qui peut le cas échéant en référencer plusieurs.

2 - Optionel La notice Common Changelog

Je suggère donc d'utiliser la notice pour faire le lien vers les pull requests source du changement, et de ne pas l'utiliser à d'autres fins.

3 - La qualification des changements d'openfisca-france

De mon point de vue, les informations essentielles données par la forme actuelle du changelog des modèles OpenFisca se retrouvent dans le format Common Changelog, dans une présentation différente mais qui rend le résumé au format actuel redondant.
Je trouve d'ailleurs que les catégories que nous avions décrites il y a longtemps (Évolution du système socio-fiscal. | Amélioration technique. | Correction d'un crash. | Changement mineur.) ne sont pas très pertinentes à l'usage : dans un modèle OpenFisca, il ne devrait y avoir quasiment que des évolutions du système socio-fiscal. Et qu'est-ce qu'un « changement mineur » ?

Je serais donc d'avis, si l'on veut s'appuyer sur Common Changelog, d'en débloquer la puissance en respectant réellement le standard et en faisant rentrer les informations nécessaires dans le format Common Changelog, c'est-à-dire en qualifiant les évolutions du système socio-fiscal comme des ajouts, modifications, suppressions.

C'est déjà le choix qui a été fait pour la qualification SemVer : l'API publique considérée pour déterminer la version SemVer est celle du modèle. Refléter ce choix dans Common Changelog permettrait d'envisager l'automatisation du calcul du numéro de version.

Ma proposition est donc de supprimer entièrement ce paragraphe, afin de respecter le format Common Changelog, et d'indiquer les informations associées dans les change groups.

4 - Les changements (Change groups de common-changelog)

Par cohérence avec le reste du projet, je propose de les traduire

Là encore, traduire, c'est casser la compatibilité avec tout l'écosystème d'outils Common Changelog. Je suggère donc de conserver le nommage d'origine.

C'est dans les change groups qu'il faut à mon sens mandater le plus de détails, afin de retrouver la « zone impactée » (qui n'ont peut-être pas besoin de lister des fichiers dont la liste peut être obtenue directement sur GitHub ou dans Git) et les « périodes concernées ». Par exemple, pour la v6.0.1 :

6.0.1 - 2023-07-31

Pour les changements détaillés et les discussions associées, consultez la pull request #174.

Changed

• Modifie l'implémentation du paramètre taux_incapacité dans la réforme dynamique Aides-Jeunes, sans changement des résultats des calculs

Les releases github

Oui, il me semble important de créer des tags pour chaque release. Je suis surpris que ça ne soit pas déjà le cas sur France-Local. Ça n'est pour autant pas urgent.

L'automatisation

Je confirme la pertinence et la puissance de l'automatisation des releases sur la base de Common Changelog (cf. OpenTermsArchive/engine#957). Le coût de mise en place n'est pas négligeable, mais cela fluidifie les releases et je crois que la fréquence de release sur un modèle comme France le justifierait vraiment, ce d'autant plus qu'il s'agit d'une friction systématique pour les nouveaux contributeurices.

Je suggèrerais donc de tester la mise en place d'un changelog compatible avec Common Changelog, de tester les limites et l'appropriation puis, en cas de succès, d'envisager l'automatisation 🙂

On peut d'ailleurs, en ce sens, commencer par traduire les intitulés des change groups en français (car ce morceau d'anglais dans les titres est choquant, j'en conviens), et envisager la traduction en masse lorsqu'on se préoccupera de l'automatisation.

[Allan-CodeWorks]

Merci beaucoup @MattiSG pour ce retour complet et précis!
J'ai fait les modifications pour pour s'accorder avec Common Changelog et tes retours.

En résumé, il me semble que nous avons donc un respect total du format Common Changelog avec une particularité : la notice limitée à une référence vers la Pull Request en question.

[Allan-CodeWorks]

@MattiSG Pour ce qui est de l'automatisation, je me permets de préciser quelques détails :

• La publication automatique de nouveaux tags git pour chaque version est bien en place sur ce dépôt
• La publication automatique du package PyPi de chaque nouvelle version est également en place

L'automatisation dont je parlais est celle des release Github qui est une fonction propre a Github, ni openfisca-france ni openfisca-core n'utilisent cette fonction. C'est juste une recommandation de Common Changelog que j'ai essayé de mettre en place mais je ne suis pas convaincu de la valeur.

A première vue, une éventuelle vérification du fichier CHANGELOG.md pour vérifier le respect du format Common Changelog pourrait être confortable mais l'œil humain lors des reviews est déjà présent.

[MattiSG]

Bravo, ça me semble super et c'est une amélioration vraiment bien construite ! J'ai hâte de voir à l'usage ce que ça donnera, si les informations seront plus pertinentes que ce qu'on a ailleurs, et le cas échéant de répliquer sur tout l'écosystème ! 👏

[MattiSG]

Suggested change

	Le niveau des évolutions d'OpenFisca-France-Local doivent pouvoir être comprises par des réutilisateurs qui n'interviennent pas nécessairement sur le code.
	Les descriptions des évolutions d'OpenFisca-France-Local doivent pouvoir être comprises par des personnes qui n'interviennent pas nécessairement sur le code.