Fork: 0
tdm / web-services
Transfer to URL with SHA Find file
Newer
Older
web-services / CONTRIBUTING.md
@François Parmentier François Parmentier on 29 Jun 2023 12 KB docs(contributing): Ajout de la fiche du service
Raw Blame History

Bonnes pratiques

Développement

Avant de programmer

Cloner le dépôt

Il faut avoir cloné le dépôt sur sa machine:

git clone ssh://git@gitbucket.inist.fr:22222/tdm/web-services.git

Cette étape n'est nécessaire qu'une seule fois.

Se mettre dans le répertoire web-services

On réutilise toujours le même répertoire de travail (normalement nommé par la commande précédente web-services).

Synchronisation

Avant de commencer la création d'un nouveau service, on rapatrie les dernières modification du dépôt (à partir de la racine, c'est-à-dire le répertoire web-services):

git pull

Nouvelle branche

En fonction de ce que vous voulez faire, créez une branche:

  • create-service où vous remplacez service par le nom du service que vous envisagez de créer
  • fix-service où vous remplacez service par le nom du service que vous envisagez de corriger
  • improve-service où vous remplacez service par le nom du service que vous envisagez d'améliorer

Exemples de noms de service (qui correspond au nom de l'instance suivi de la route du service à créer):

  • terms-extraction-v1-teeft-de,
  • affiliations-tools-v1-ror

Le nom de la branche doit rester compréhensible.
Techniquement, le nom de la branche n'est pas très important, mais il l'est pour l'équipe (par exemple, pour savoir ce qui est déployé en vi)

git checkout master # on s'assure qu'on est sur la branche principale
git checkout -b create-service # on crée la branche et on s'y déplace

Pull Request

Créez une pull request où vous pourrez documenter plus largement que dans les messages de commit ce que vous faites.
Ça permet également d'avoir une discussion portant sur la modification en cours.
Ça permettra aussi de montrer votre code à quelqu'un d'autre avant de le valider.
La pull request se crée à partir de la branche que vous avez créée, mais elle doit au moins contenir un commit.

Sur le menu Pull requests de GitBucket cliquez sur New pull request (en haut à droite de la page).

bouton de création d'une PR

Si vous ne voyez pas le bouton, connectez-vous à GitBucket.

bouton de connexion

Par défaut, on tombe sur une page comparant la branche master à... la branche master.

Comparaison par défaut

Comme vous avez déjà poussé votre branche, vous pouvez la sélectionner (à droite):

Page de création de PR

Il est important de donner un titre et une description parlante à votre pull request, c'est ce qui permettra de la retrouver facilement.
En général, le titre est lié au nom de la branche, si on a été bien inspiré en créant la branche.

formulaire de description de la PR

Comme la pull request est dédié à la communication entre nous, on peut y écrire en français (dans un projet open source classique, on préfère utiliser l'anglais).

PR créée

Il ne reste plus qu'à continuer à travailler dans la branche de la pull request, en n'oubliant pas de pousser régulièrement les commits sur le dépôt.

git push

💡 Note: Si vous collaborez avec une autre personne dans la branche de la pull request, n'oubliez pas de faire un git pull, avant de modifier vos fichiers.
L'utilisation de VSCode peut aider, il vérifie régulièrement si une synchronisation est nécessaire.

Nouvelle instance ?

Vérifier si une instance existante serait réutilisable

Les instances rassemblent des services:

  • dans le même thème
  • partageant des dépendences techniques (type de worker)

Par exemple, affiliations-tools regroupe addresses, netscity et rnsr, qui travaillent tous les affiliations (même thème).

Les biblio-tools, partagent certes un même thème, mais ne dépendent que de ezs, d'où leur utilisation de lodex-workers, le plus léger des workers (python n'y est pas installé, ni aucun paquet comme libpostal).

Moins il y a d'instances, moins le serveur de production a besoin d'être puissant (et c'est meilleur pour la planète).
Dans la mesure du possible, essayez donc d'ajouter vos services dans des instances existantes (les instances ont chacun un répertoire à la racine du dépôt, et respectent la convention de nommage).

Si aucune instance n'est réutilisable

Lorsqu'on n'a pas d'autre choix que de créer une instance, il faut:

  • déterminer un nom d'instance en suivant les conventions de nommage (un tiret au milieu, ...)
  • création du répertoire de l'instance (les deux premières parties du nom de l'instance, séparées par un tiret)
  • création de la route v1/... en fonction des répertoires et du fichier .ini.
  • création de swagger.json, contenant le numéro de version de l'instance (0.0.0)
  • création de examples.http
swagger.json de base

Le champ info.version doit contenir 0.0.0, car il sera modifié lors de la création de version.

On peut créer un ou plusieurs tags à affecter à chaque service.
Il leur faut un name parlant, court et une description un peu plus longue (mais pas trop). Ces deux champs apparaissent dans l'OpenAPI.
On ajoute aussi un externalDocs qui pointe sur le README de l'instance. Lui aussi sera présent dans l'OpenAPI. 

{
    "info": {
        "version": "0.0.0"
    },
    "tags": [
        {
            "name": "terms-extraction",
            "description": "Extraction de termes",
            "externalDocs": {
                "description": "Plus de documentation",
                "url": "https://gitbucket.inist.fr/tdm/web-services/tree/master/terms-extraction"
            }
        }
    ]
}

Exemple pour ces tags:

tags de l'OpenAPI

Dans tous les cas

Création du .ini: v1/service.ini

Chemin du .ini détermine la route du service. Avec les métadonnées de base: description, summary, tags... Modèle de base en ezs pur / avec python. À COMPLÉTER

Python

version de python

Utiliser un environnement virtuel

requirements.txt

programme python

Nommer le programme python comme le .ini (mais c'est le .ini qui détermine la route du service).

Tester localement

node

Tester localement

Documentation

paquets ezs

examples.http

Déploiement

Tester sur la vi

Déployer le service sur la vi

La version de la branche.

Tester le swagger

www-home

Si c'est une nouvelle instance, l'ajouter dans le index.html de www-home, qui sera openapi.services.inist.fr.

Code review

Merge vers master

Faire une version

Vérifier l'utilisation (grafana)

S'assurer, via le tableau de bord de Grafana, que l'instance en question n'est pas sollicitée.
Le but est de ne pas casser une série de requêtes en cours.

Suivi d'utilisation via Grafana

Déployer sur la vp

La version générée instance@version.

Utiliser les dépendances de la vi pour mettre à jour celles de la vp.

Configuration de la vi

Cas d'une nouvelle instance

  1. ajouter l'instance dans internal-proxy À COMPLÉTER
  2. ajouter l'instance dans internal-monitoring À COMPLÉTER

Après le déploiement

Vérifier que le swagger fonctionne

Si c'est une nouvelle instance, il se peut qu'elle n'apparaisse pas immédiatement dans openapi.services.inist.fr, car ce site est mise à jour automatiquement toutes les demi-heures (pendant les heures de bureau, les jours de semaine).

Une fois que https://openapi.services.inist.fr/ affiche les routes que vous venez de développer / corriger / documenter, utilisez le bouton Try it out sur cette/ces route/s:

bouton try it out

Puis, le bouton Execute.

bouton Exeute de l'OpenAPI

Le résultat doit correspondre à l'exemple (avec un code 200).

le résutat de l'exécution via OpenAPI

catalogues LODEX

Signaler dans le canal mattermost #TDM les nouvelles routes, pour qu'elles puissent être ajoutées au catalogues de LODEX.

signalement dans mattermost

Objectif TDM

Fiche du service

La fiche d'un service web doit avoir (le titre d'une section sera en style Titre 3):

  • titre: le plus court et explicite possible
  • sous-titre: la première phrase de la fiche fera office de description dans la prévisualisation présente sur la page d'accueil d'objectif TDM, il faut donc aller droit au but, pas besoin de construire une phrase. Si la phrase est trop longue, il est possible qu'on n'en voie que le début
  • description: plus longue et détaillée que le sous-titre, décrit ce que fait le service web.
  • image: idéalement, un usage de l'enrichissement dans LODEX
  • algorithme: une section consacrée à la manière dont fonctionne le service (est-ce un apprentissage, une heuristique, ...)
  • qualité: une section donnant une idée de la qualité du service (expérimental, avec des retours utilisateurs, avec une f-mesure, rappel, bruit, précision, ...). Ne s'applique pas de la même manière suivant les algorithmes.
  • corpus d'apprentissaga / test: sur quelles données s'appuient les tests et/ou l'apprentissage
  • références: bibliographie + code source (liens)

Exemple de sous-titre trop long:

Sous-titre n'allant pas droit au but

La catégorie à affecter à la fiche est Web-services, pas Blog/Webservices.

catégorie de la fiche

Blocs à remplir:

  • URL Lodex: on y met l'URL du service
  • Entrée: généralement un JSON, on utilise l'extension Code Block pour coloriser le code et garder les indentations.
  • Résultat: comme l'Entrée.
  • Utiliser: lien vers l'OpenAPI
  • Se documenter: lien vers l'article générique https://objectif-tdm.inist.fr/se-documenter/

blocs à remplir

Article d'annonce