Release management

Un/e développeur/se qui va chercher un jeu de données sur https://data.tricoteuses.fr/ s’attend à trouver une documentation, des schemas et des données cohérentes, au même niveau de version. Les dépots concernés sont:

Et le rendu est sur:

A chaque fois qu’un commit est ajouté dans l’un des dépots, une nouvelle release doit être faite.

Et cela peut être fait automatiquement si la validation des données par les schemas JSON passe. Sinon le tag de version (v3) pour les dépots qui contiennent les données et les schemas qui échouent sont ramenés sur le tag de la version précédente (v2) (qui passe la validation, par définition).

Dans le cas limite ou aucun dépot ne passe la validation, il n’est pas nécessaire de faire la release parce qu’elle serait identique à la précédente.

Cette stratégie permet de publier une release avec des mises à jour pour N dépots, même si N dépots de données ne peuvent pas être mis à jour.

Une intervention manuelle est nécessaire pour corriger les erreurs de validation. A chaque fois qu’une erreur est corrigée et que la HEAD d’un dépot passe la validation, le process de release peut être relancé.

Qu’en pensez-vous ?

Après discussion avec une personne qui travaille sur des données associées à des schémas XML ou JSON, il semble utile d’ajouter un numéro de version aux données. Par exemple:

{
  "schemaVersion": 2.1,
  ...
}

Plutôt que d’appliquer un numéro de version aux dépôts de données. De cette façon il est assez simple de faire cohabiter des données de format différents tout en gardant la possibilité de les valider. Ca correspond aussi assez bien avec le fait que les données sont, pour la plupart, immutables.

Le release management concerne donc surtout les schemas JSON et pas les données. L’effort de compatibilité ascendante porte sur le schema et pas sur les données. Dans l’hypothèse ou un jeu de donné est transformé, la version du schema est aussi mise à jour.

Pour éviter de forcer les logiciels à prendre en compte un nouveau format qui n’est pas compatible dès qu’il est publié, il faudrait continuer à publier les données dans l’ancien format.

La validation d’un jeu de donné a besoin de tous les version de schemas auquelles les fichiers JSON auteur font référence. Par exemple, si 2.0 et 2.1 existent, la validation doit checkout:

Cela suppose que

  • des tags de version sont ajoutés à chaque release d’un schema (par exemple schema-acteur-2.1)
  • tout les fichiers composant le schema pour un jeu de donné sont regroupés dans un dossier (par exemple acteur)

Pour illustrer la proposition, une merge request implémente un script de validation JSON qui prend en compte la version.

La merge request est dans master depuis hier mais n’est pas encore utilisée parce que les données n’ont pas de champ schemaVersion. On pourrait procéder comme ça:

  • Ajouter “schemaVersion”: “acteur-1.0” pour tout les acteurs etc.
  • Normalement ça ne change rien parce que c’est c’est la valeur par défaut
  • Quand un changement de schema est nécessaire:
    • Modification du schema (par exemple acteur/Acteur.json) et vérification avec validate_json.ts --dev
    • Incrémenter le numéro de schema, “schemaVersion”: “acteur-1.1” si c’est backward compatible ou “schemaVersion”: “acteur-2.0” si c’est un breaking change dans tout les JSON qui ont besoin du nouveau schema
    • Ajouter un tag schema-acteur-1.1 ou schema-acteur-2.0 sur tricoteuses-assemblée
    • Push le tag

Et validate_json.ts va chercher les schemas correspondant au champ schemaVersion en extrayant les fichiers qui sont dans tricoteuses-assemblee au tag correspondant. Les tests de validate_json.ts et la fonction correspondante donnent une idée de la logique.

L’ajout de schemaVersion pour les nouveaux fichiers est implémenté et le README indique comment placer les tags de version de schema.