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.
web-services
On réutilise toujours le même répertoire de travail (normalement nommé par la commande précédente web-services
).
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
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éerfix-service
où vous remplacez service
par le nom du service que vous envisagez de corrigerimprove-service
où vous remplacez service
par le nom du service que vous envisagez d'améliorerExemples 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
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).
Si vous ne voyez pas le bouton, connectez-vous à GitBucket.
Par défaut, on tombe sur une page comparant la branche master
à... la branche master
.
Comme vous avez déjà poussé votre branche, vous pouvez la sélectionner (à droite):
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.
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).
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.
Les instances rassemblent des services:
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).
Lorsqu'on n'a pas d'autre choix que de créer une instance, il faut:
.ini
.swagger.json
, contenant le numéro de version de l'instance (0.0.0
)examples.http
.ini
Avec les métadonnées de base: description, summary, tags...
À COMPLÉTER
swagger.json
de baseLe 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"
}
}
]
}
Nommer le programme python comme le .ini
(mais c'est le .ini
qui détermine la route du service).
La version de la branche.
Si c'est une nouvelle instance, l'ajouter dans le index.html
de www-home
, qui sera openapi.services.inist.fr
.
La version générée instance@version
.
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).