search

datagouv / schema.data.gouv.fr

Schémas de données ouvertes sur des formats réglementaires ou non
https://schema.data.gouv.fr
MIT License
41 stars 27 forks source link

Points d'ergonomie pour les contributeurs #212

Open thbar opened 2 years ago

thbar commented 2 years ago

Je fais une sorte de méta-action pour grouper mes feedbacks suite à la place en place de #208.

Je ne suis pas sûr à 100% que c'est le bon endroit, et ce n'est pas non plus une liste au père Noël, juste des retours pour partager.

Gestion des liens relatifs dans les README

Actuellement si un lien relatif existe dans un README (voir exemple ici https://github.com/etalab/schema-comptage-mobilites-channel/blob/c90733f864384a9f11e506c21ea8f7faca4081df/README.md#fichiers-disponibles), les liens sont cassés lorsqu'on publie une version de schéma (voir #208 par exemple).

Au final on va pour l'instant supprimer les liens relatifs, mais c'est un peu dommage car c'est vraiment pratique de les avoir dans un README pour les contributeurs (il est plus facile d'explorer ex: un lien vers GitHub actions etc).

Dans l'immédiat notre solution va être de supprimer les liens relatifs complètement, toutefois je voulais faire ce retour qui pourra impacter d'autres utilisateurs.

Une solution pourrait être de n'avoir aucun lien relatif dans le README, et d'avoir une autre section CONTRIBUTING qui elle aurait des liens relatifs (plutôt ciblés pour les contributeurs).

Liens exemples dans schema.json

Un peu dans le même esprit, si j'ai compris il est nécessaire que schema.json pointe vers les fichiers d'exemples en version taguée (ex https://github.com/etalab/schema-comptage-mobilites-channel/commit/c90733f864384a9f11e506c21ea8f7faca4081df), cf https://github.com/etalab/schema.data.gouv.fr/issues/208#issuecomment-979873300.

Cela réduit un peu l'ergonomie pour un contributeur ou même quelqu'un qui consulte le schéma via GitHub (jusqu'à la prochaine release, le lien pointe sur une version qui n'est pas raccord ; si techniquement on voulait vérifier que l'exemple pointé est bon à chaque commit, pour industrialiser, ça ne marcherait pas etc).

Ca paraît compliqué à gérer côté "schema data gouv" ; je me demande si avoir une GitHub action de nos côtés qui irait simplement modifier les liens lors des releases, serait une bonne solution.

Support multi-schemas dans un repo unique

Sur #208 on a 3 repositories (et ce cas va se reproduire vu ce qu'on va traiter, même si on cherche à éviter au maximum). Du coup la gestion de la publication est plus laborieuse : toute édition doit se faire 3 fois, les erreurs sont faites 3 fois aussi, il faut tagger 3 fois etc etc.

On est preneur de consolidation à un moment, comme évoqué dans https://github.com/etalab/schema.data.gouv.fr/issues/208#issuecomment-979873300.

geoffreyaldebert commented 2 years ago

merci @thbar pour cet issue. C'est bien noté et on va voir dans quelle mesure on peut prendre en compte ces éléments :

Liens relatifs C'est probablement le plus facile. Il faut que nous modifions notre process de récupération interne des markdown et convertissions tous les liens relatifs avec l'url github lors de l'ajout des pages sur schema.data.gouv.fr

Liens dans schemas.json Effectivement, cela peut être embêtant, d'autant que c'est vraiment pénible de supprimer et ajouter une release uniquement à cause d'un oubli dans le nom de l'url, qui n'existait pas encore au moment de l'ajout. C'est une limite pour le moment de cette spécification mais d'expérience, une fois connue, on y fait attention. Ta proposition de github actions pourrait en effet être une des pistes.

Multi-schéma C'est effectivement un sujet sur lequel je me suis promis d'avancer début 2022. On en reparle très vite.