Comment contribuer au Socle commun des données locales (SCDL) ?
Tous les schémas du SCDL sont référencés dans le Catalogue des schémas SCDL.
L'ajout d'un schéma au catalogue se fait en proposant d'amender le fichier catalog.json sous forme de merge request.
Critères d'acceptation
OpenDataFrance se réserve le droit d'accepter ou de refuser l'ajout d'un schéma au sein du SCDL.
Pour faire partie du SCDL, un schéma doit :
- être écrit en JSON conformément aux spécifications Table Schema. Les métadonnées du schéma doivent employer les propriétés qui ont été standardisées, avec au minimum :
name
: identifiant, ou "slug" ;title
: nom courant ;description
;homepage
: page d'accueil ou dépôt Git ;path
: URL de cette version du schéma ;created
: date de création ;lastModified
: date de publication de cette version ;version
: le numéro de version au format SemVer ;
- être nommé
schema.json
; - être accompagné d'un fichier
README.md
complet, présentant notamment le contexte de sa création ; - être mis à disposition en ligne sur une URL stable.
Optionnel :
- être mis à disposition dans un dépôt Git afin de bénéficier de la gestion des versions (voir ci-dessous) ;
- un fichier
CHANGELOG.md
peut être publié au même endroit que le fichierschema.json
afin d'apporter des informations sur les différentes mises à jour du schéma ; - des données tabulaires d'exemple sous forme de fichiers CSV, valides ou invalides, peuvent également être ajoutées dans un dossier séparé (et référencées dans le schéma grâce à la propriété
resources
).
Cycle de vie d'un schéma SCDL
Contribution
Concerne la création initiale ou la mise à jour d'un schéma.
Une contribution se fait toujours dans une branche, la branche master
étant protégée. Plusieurs branches peuvent coexister lorsque différentes évolutions n'ont pas la même nature.
Lorsqu'un changement est cassant, penser à mettre à jour le fichier d'exemple valide pour qu'il reste valide.
Le contributeur ne doit pas nécessairement mettre à jour CHANGELOG.md
ni le numéro de version dans schema.json
(à faire lors de l'intégration et de la publication).
Lorsque le contributeur n'est pas membre de l'équipe, il travaillera dans un fork du dépôt du schéma.
Lorsqu'une branche est prête à être proposée, le contributeur ouvre une merge request.
Intégration
Concerne la revue et l'acceptation des changements proposés par un contributeur.
L'intégrateur est celui qui a les droits d'écriture sur la branche master
. Après vérification de la merge request, il peut fusionner la branche dans master
. Ainsi master
accumule un certain nombre de modifications par rapport à la dernière version publiée.
Conséquence : le fichier catalog.json
ne doit pas référencer les schémas depuis master
mais depuis des URLs contenant un tag (cf ci-dessous).
L'intégrateur doit tenir à jour une section prévisionnelle dans le CHANGELOG.md
de type "X.Y.Z -> next" où "X.Y.Z" est la dernière version publiée et "next" est un marqueur qui sera remplacé par le nouveau numéro de version lors de la publication. Cette section doit être placée tout en haut du fichier (le plus récent en premier).
Publication d'une version ("release")
Cette dernière étape consiste à rendre visibles et utilisables, notamment sur Validata, les changements accumulés dans master
depuis la dernière version publiée. Il s'agit de figer, à un instant t et dans un ensemble cohérent, tous les fichiers du dépôt du schéma (schéma, documentation, fichiers exemples, etc.).
Les schémas SCDL suivent le principe du semantic versioning.
L'objectif est d'attribuer un nouveau numéro de version au schéma. Pour cela :
- déterminer si l'ensemble des modifications depuis la version précédente est rétrocompatible ou non ("cassant") ;
- mettre à jour le numéro de version en conséquence (majeur, mineur ou patch) dans
schema.json
:version
;lastModified
: date de mise à jour ;path
etresources
: mise à jour de l'URL avec le bon tag de version ;
- ajouter ou modifier l'entrée dans le
CHANGELOG.md
(le plus récent en haut) qui décrit les changements rétrocompatibles et non-rétrocompatibles dans 2 listes séparées (exemple ; - faire un commit de release qui ne contienne que les 2 points précédents, dont le message est "Version X.Y.Z" (remplacer X.Y.Z) ;
- tagger ce commit avec
vX.Y.Z
(remplacer X.Y.Z) ; - pusher 2 fois :
git push origin master
etgit push --tags
.