diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bd1d000..42a5673 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,35 +2,47 @@ - [Bonnes pratiques](#bonnes-pratiques) - [Développement](#développement) - - [Avant de travailler](#avant-de-travailler) + - [Avant de programmer](#avant-de-programmer) - [Cloner le dépôt](#cloner-le-dépôt) - [Se mettre dans le répertoire `web-services`](#se-mettre-dans-le-répertoire-web-services) - [Synchronisation](#synchronisation) - [Nouvelle branche](#nouvelle-branche) - [Pull Request](#pull-request) - [Nouvelle instance ?](#nouvelle-instance-) + - [Vérifier si une instance existante serait réutilisable](#vérifier-si-une-instance-existante-serait-réutilisable) + - [Si aucune instance n'est réutilisable](#si-aucune-instance-nest-réutilisable) + - [Création du `.ini`](#création-du-ini) + - [`swagger.json` de base](#swaggerjson-de-base) + - [Dans tous les cas](#dans-tous-les-cas) - [Python](#python) - [version de python](#version-de-python) - [Utiliser un environnement virtuel](#utiliser-un-environnement-virtuel) - [requirements.txt](#requirementstxt) + - [programme python](#programme-python) - [Tester localement](#tester-localement) - [node](#node) - [Tester localement](#tester-localement-1) - [Documentation](#documentation) - [paquets ezs](#paquets-ezs) - [examples.http](#exampleshttp) - - [Tester le swagger](#tester-le-swagger) - [Déploiement](#déploiement) - [Tester sur la vi](#tester-sur-la-vi) + - [Déployer le service sur la vi](#déployer-le-service-sur-la-vi) + - [Tester le swagger](#tester-le-swagger) + - [www-home](#www-home) + - [Code review](#code-review) + - [Merge vers master](#merge-vers-master) + - [Faire une version](#faire-une-version) - [Vérifier l'utilisation (grafana)](#vérifier-lutilisation-grafana) - [Déployer sur la vp](#déployer-sur-la-vp) - [Après le déploiement](#après-le-déploiement) + - [Vérifier que le swagger fonctionne](#vérifier-que-le-swagger-fonctionne) - [catalogues LODEX](#catalogues-lodex) - [Objectif TDM](#objectif-tdm) ## Développement -### Avant de travailler +### Avant de programmer #### Cloner le dépôt @@ -69,6 +81,17 @@ - `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](#déployer-le-service-sur-la-vi)) + ```bash 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 @@ -122,18 +145,87 @@ 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 +#### Vérifier si une instance existante serait réutilisable -Si non: +Les instances rassemblent des services: -- déterminer un nom d'instance en suivant les conventions de nommage (un tiret - au milieu, ...) -- création du répertoire de l'instance -- création de la route v1/... +- dans le même thème +- partageant des dépendences techniques (type de worker) -Dans tous les cas: +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](README.md#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](README.md#nom-de-linstance) (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](README.md#nom-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` + +##### Création du `.ini` + +Avec les métadonnées de base: description, summary, tags... + +À COMPLÉTER + +##### `swagger.json` de base + +Le champ `info.version` doit contenir `0.0.0`, car il sera modifié lors de la +[création de version](#faire-une-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. + +```json +{ + "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](https://openapi.services.inist.fr/?urls.primaryName=terms-extraction%20-%20Extraction%20de%20termes#/terms-extraction): + +![tags de l'OpenAPI](images/openapi-tags.png) + +#### Dans tous les cas - création du .ini v1/service.ini @@ -145,6 +237,11 @@ #### 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 diff --git a/README.md b/README.md index e2fde2d..b4d656c 100644 --- a/README.md +++ b/README.md @@ -285,7 +285,8 @@ contenir des chiffres) et de préférence en anglais. Si le premier niveau caractérise obligatoirement la version, les suivants peuvent être adaptés selon le besoin. -On veillera à créer un répertoire si et seulement si il propose plusieurs sous-répertoire ou fichiers. +On veillera à créer un répertoire si et seulement si il propose plusieurs sous-répertoire ou fichiers. +Plus le chemin est court, mieux c'est. 1. Version des APIs (v1, v2, v3, etc.) 2. Nom de l'algorithme ou de la ressource utilisés ou de la langue @@ -297,6 +298,7 @@ - `/v1/test/analyse` - `/v2/istex/expand` - `/v1/en/stemmer/analyse` +- `/v1/teeft/fr` ### Fichier d'exemple diff --git a/images/openapi-tags.png b/images/openapi-tags.png new file mode 100644 index 0000000..f392738 --- /dev/null +++ b/images/openapi-tags.png Binary files differ