Publier le modèle NGC sur NPM et l'utiliser côté site

[EmileRolley]

Contexte

Jusqu'à présent, le modèle est mis à jour en poussant sur master puis les fichiers JSON compilés sont déployés sur le serveur netlify à l'adresse : https://data.nosgestesclimat.fr. Les fichiers JSON sont ensuite récupérés par l'application web.

Problème

Avec cette méthode, il est très facile d'introduire des modifications cassantes dans le modèle. Par exemple, si une des règles est renommées, et que le changement n'est pas répercuté dans l'application web, alors il est possible que l'application web ne fonctionne plus.

De plus, il est difficile d'associer une version du modèle à une situation Publicodes donnée. En effet, cela pourrait permettre de savoir quelle version du modèle utiliser si une personne a effectué un calcul à une date donnée et ainsi de pouvoir éviter les régressions. On pourrait également imaginer d'associer à chaque nouvelle version cassante du modèle un script de migration permettant de mettre à jour les situations d'une version à l'autre.

Solution

Pour résoudre ce problème, nous allons mettre en place un système de versionnage du modèle et modifier le processus de développement de celui-ci.

Utilisation du modèle versionné

Paquet NPM

Des travaux antérieurs ont permis de mettre en place un système de paquets NPM permettant la réutilisation des règles dans d'autres modèles Publicodes ou bien d'importer les règles dans un projet JS.
Cependant, le modèle NGC a la particularité d'être régionalisé, traduit et optimisé. Ainsi, pour chaque version du modèle, les règles du modèle sont compilées en 72 fichiers JSON de 500 à 800 Ko chacun.

Il parait donc peu judicieux de publier l'ensemble des fichiers sur NPM. De plus, côté application web, une seule version du modèle est utilisée à la fois et il serait donc inutile de charger l'ensemble du paquet NPM côté client.

💡 N'est-il pas possible avec NextJS de ne charger le paquet NPM que côté serveur, et d'envoyer uniquement les règles utilisées côté client ?

Quand bien même, on trouverait une solution pour charger uniquement les règles utilisées côté client, il faudrait tout de même publier l'ensemble des fichiers sur NPM et il serait compliqué d'utiliser des versions antérieures du modèle.

API REST (solution retenue)

Une solution plus adaptée serait d'utiliser l'API REST Publicodes pour récupérer les règles d'une version donnée. Cela permettrait de ne pas avoir à publier l'ensemble des fichiers sur NPM et de pouvoir utiliser des versions antérieures du modèle.

On pourrait imaginer une API REST de la forme :

https://data.nosgestesclimat.fr/<version>/<langue>/<region>/<route>

Avec :

• version - la version du modèle à utiliser, (latest pour la dernière version)
• langue - la langue à utiliser (fr ou en)
• region - la région à utiliser (FR, CA, BE, CH, etc...)
• route - la commande à effectuer parmi :
  • rules : retourne l'ensemble des règles du modèle
  • rules-optim : retourne l'ensemble des règles du modèle optimisé
  • rules/{rule} : retourne la règle {rule} du modèle
  • evaluate : évalue une règle avec la situation passée en paramètre
  • versions : retourne l'ensemble des versions du modèle
  • versions/{version} : retourne les informations de la version {version} (date, notes de version, scripts de migrations, langues et régions supportées)
  • personas : retourne l'ensemble des personas du modèle

💡 On peut tout de même imaginer publier sur NPM la version FR-fr du modèle à fin d'en faciliter l'utilisation dans d'autres modèles Publicodes ou dans les scripts de tests.

💡 On peut imaginer une version nightly du modèle qui serait synchronisée avec la branche preprod du dépôt nosgestesclimat.

Processus de développement

Le processus de développement du modèle sera le suivant :

1. Création d'une branche preprod à partir de master
2. Création de branches feature et fix à partir de preprod
3. Une fois toutes les fonctionnalités développées, un recettage exhaustif est effectué sur la branche preprod
4. Une fois le recettage terminé, la branche preprod est mergée dans master
5. Un nouveau tag est créé selon le versionnage sémantique, une release lui est alors automatiquement associée sur github et le modèle est compilé et publié sur NPM.

Implémentation

Gestion des versions

On aurait donc un nouveau dépôt nosgestesclimat-api qui contiendrait le code du serveur et qui serait déployé sur Netlify à l'adresse https://data.nosgestesclimat.fr (ou autre ?).

J'imagine deux solutions pour gérer les versions du modèle côté serveur :

1. Pour chaque nouvelle release du modèle on ajoute un sous dossier dans un dossier versions du dépôt nosgestesclimat-api qui contiendrait l'ensemble des fichiers JSON compilés du modèle et les personas. (solution préférée)

   Ainsi, à chaque modification le serveur est redéployé avec l'ensemble des versions du modèle.

2. Le serveur n'est déployé qu'une seul fois, et met à jours sont contenu dynamiquement.

   On peut donc imaginer qu'il ne récupère uniquement les règles de base et se fasse de la compilation JIT pour chaque requête. Cela permettrait de ne pas avoir à redéployer le serveur à chaque nouvelle release du modèle.

Contenu écrit du modèle

Les notes de version actuelles et plus généralement l'ensemble du dossier contenu-ecrit seront migrées dans le dépôt -site.

Application web

Il faudra également modifier l'application web pour qu'elle utilise l'API REST afin de récupérer les règles du modèle.

💡Une première version serait simplement de remplacer l'URL de l'API actuelle (https://data.nosgestesclimat.fr/co2-model.<region>-lang.<lang>{-opti}.json) par https://data.nosgestesclimat.fr/latest/<region>/<lang>/rules{-optim}.

Tâches

MVP

nosgestesclimat-api:

• Créer le dépôt nosgestesclimat-api
• Implémenter l'API REST
• Mettre en place le déploiement sur netlify
• Mettre en place le déploiement automatique à chaque nouvelle release du
  dépôt nosgestesclimat

nosgestesclimat:

• Passer à en-us partout au lieu de en
• Migrer le contenu écrit dans le dépôt -site
• Supprimer les dossiers contenu-ecrit et public du dépôt
  nosgestesclimat
• Setup la CI pour la publication de releases sur NPM et GitHub
• Mettre à jour la documentation

nosgestesclimat-site-nextjs:

• Modifier l'application web pour qu'elle utilise l'API REST
• Mettre à jour la documentation

Améliorations

• Gérer les versions cassantes du modèle
• Associer une version du modèle à une situation donnée (côté site)

Questions

1. Où est-ce que doit être stocké les personas ? Doivent-ils être versionnés et publiés sur NPM ? Dois-t-on rajouter une route personas à l'API REST ?
2. Comment gérer les versions du modèle côté serveur ? (voir section Gestion des versions)
3. On commencerait à avoir pas mal de dépôts différents autour de NGC, ne serait-il pas le temps de créer une orga GitHub pour les regrouper ?

[Clemog]

1. Où est-ce que doit être stocké les personas ? Doivent-ils être versionnés et publiés sur NPM ? Dois-t-on rajouter une route personas à l'API REST ?

Je dirais qu'ils doivent rester côté modèle et également versionnés ce qui peut nécessiter un script qui vérifie l'exhaustivité des règles (comme dans l'ancienne page "Personas")

2. Comment gérer les versions du modèle côté serveur ? (voir section Gestion des versions)

Pour la solution 1 également, je ne suis pas sur de bien comprendre la 2

3. On commencerait à avoir pas mal de dépôts différents autour de NGC, ne serait-il pas le temps de créer une orga GitHub pour les regrouper ?

Yes !

[florianpanchout]

Assez aligné avec tout ça. Pas trop d'avis pour les personas et je penche aussi pour la solution 1 (qu'il sera toujours temps de faire évoluer si elle finit par ne plus convenir). Et créons autant de repo que l'on veut dans l'org de l'incubateur (tout en en laissant la gestion à notre nouveau CTO), pas fan de recréer un espace à devoir gérer nous même.

Quelques détails :

• Pas sur du dans l'url alors qu'il est facultatif (et n'impacte que /rules non ?). Peut être le mettre en query param ?
• Le process de dev preprod => main pourrait être allégé. J'imagine que le site en prod appellerait une version fixe du modèle donc pas de risque de casser.

[florianpanchout]

Par contre je questionne le besoin premier : est-ce qu'on a besoin de plus de complexité que de juste avoir deux branches main / preprod ?

[EmileRolley]

pas fan de recréer un espace à devoir gérer nous même.

Ca implique beaucoup de gestion ?

• Pas sur du dans l'url alors qu'il est facultatif (et n'impacte que /rules non ?). Peut être le mettre en query param ?

Du ? J'imagine que tu parles de l'optim ? Et en effet, ça n'aurait pas trop de sens de demander /optim/personas 👌

• Le process de dev preprod => main pourrait être allégé. J'imagine que le site en prod appellerait une version fixe du modèle donc pas de risque de casser.

C'est-à-dire ? Tu ne trouves pas nécessaire de faire un recettage sur preprod avant de merge dans main ?

Par contre je questionne le besoin premier : est-ce qu'on a besoin de plus de complexité que de juste avoir deux branches main / preprod ?

Tu fais références ici au fait de stocker et d'exposer toutes les versions ?

[florianpanchout]

C'est-à-dire ? Tu ne trouves pas nécessaire de faire un recettage sur preprod avant de merge dans main ?

Si le modèle est versionné, la branche ne change pas grand chose. On aurait la version 1.12.33 de main fixé en prod jusqu'à la release suivante. Et la preprod utiliserait latest de main.

Tu fais références ici au fait de stocker et d'exposer toutes les versions ?

Yes, quel est le besoin d'exposer plusieurs versions, et est-il suffisant au regard du temps passé sur le sujet ?

[Clemog]

Si le modèle est versionné, la branche ne change pas grand chose. On aurait la version 1.12.33 de main fixé en prod jusqu'à la release suivante. Et la preprod utiliserait latest de main.

Ça me semble quand même mieux car on veut être sur ne pas introduire de bugs dans main qu'il faudrait patcher apres ?

Pour moi c'est pas forcément un recettage sur le site mais plus côté modèle, au niveau des personas entre autres

Yes, quel est le besoin d'exposer plusieurs versions, et est-il suffisant au regard du temps passé sur le sujet ?

Je suis peut etre coté mais j'avais en tête que c'est important de pouvoir taper sur n'importe quelle version (si on associe une simulation à une version / on associe une version régionale à une version)

[florianpanchout]

Ça me semble quand même mieux car on veut être sur ne pas introduire de bugs dans main qu'il faudrait patcher apres ?

Et la branche de travail ne suffit pas pour ça ?

Je suis peut etre coté mais j'avais en tête que c'est important de pouvoir taper sur n'importe quelle version (si on associe une simulation à une version / on associe une version régionale à une version)

C'est à dire ? C'est important pourquoi ? Ou est-ce que ça manque actuellement ? Je peux voir le besoin pour un utilisateur qui revient mais c'est à la marge non ? Et même dans ce cas la est-ce qu'on a un interêt fort à lui servir une version précédente du modèle ?

[Clemog]

Et la branche de travail ne suffit pas pour ça ?

Oui effectivement

[Clemog]

C'est à dire ? C'est important pourquoi ? Ou est-ce que ça manque actuellement ? Je peux voir le besoin pour un utilisateur qui revient mais c'est à la marge non ? Et même dans ce cas la est-ce qu'on a un interêt fort à lui servir une version précédente du modèle ?

Pour bien comprendre, tu n'es pas favorable au fait de pouvoir accéder à n'importe quelle version du modèle ? Je ne vois pas de grande différence par rapport à l'actuel si on ne peut pas aller chercher une version spécifique ?

[florianpanchout]

Je ne dis pas que je n'y suis pas favorable. J'essaie de comprendre pourquoi on en a besoin (et donc pourquoi il faut le faire)

[EmileRolley]

Je ne dis pas que je n'y suis pas favorable. J'essaie de comprendre pourquoi on en a besoin (et donc pourquoi il faut le faire)

Le but d'utiliser des versions et de ne pas casser le code des utilisateur.ices à chaque modifs.

Après pour l'instant étant le seul utilisateur (même si Sami, Yami, Agir, ICO2 pourraient être rapidement des utilisateurs direct de l'API), simplement exposer la dernière version pourrait suffire pour une première version. Mais si on veut aller plus loins et même sur NGC pouvoir faire des projections ou comprendre l'évolution du modèle ce sera nécessaire de sauvegarder les différentes versions.

[florianpanchout]

Le but d'utiliser des versions et de ne pas casser le code des utilisateur.ices à chaque modifs.

C'est la ou je peine a saisir. La version de la personne n'est, pour l'instant, pas dépendante de sa situation.

Que l'on garde des variables en localStorage ou ailleurs (type valeur de bilan ou des catégories), ça me semble très intéressant si on veut qu'elle puisse se comparer dans le temps.

Par contre, est-ce que l'on souhaite lui permettre de refaire son test avec un ancien modèle ? Pourquoi ne pas toujours lui servir la version la plus à jour ?

[EmileRolley]

C'est la ou je peine a saisir. La version de la personne n'est, pour l'instant, pas dépendante de sa situation.

Utilisateur de l'API pas de nosgestesclimat.fr

[florianpanchout]

Ok donc le besoin est principalement orienté vers les réutilisateurs du modèle et pas vers NGC ? C'est plus clair pour moi si c'est le cas

[mquandalle]

Petit retour d'expérience, je publie les aides vélo sur NPM et ensuite dependabot ouvre une PR sur aides-jeunes pour la mise à jour du paquet. Ce process est très fluide et permet de jouer les tests d'intégration du site avant de mettre en production la mise à jour des règles publicodes.

[Clemog]

Le souci avec un paquet c'est qu'à priori on ne peut pas faire d'imports dynamiques : or, on voudrait pouvoir spécifier la région + langue du modèle importé, on s'est dit que l'API serait plus simple