Contribuer à Tock

Le projet Tock est ouvert à la contribution et toute proposition est la bienvenue !

Cette page donne des indications sur la structure et les conventions du code de la plateforme.

TL;DR

Voir CONTRIBUTING.md (anglais uniquement).

Principales technologies

L’ensemble de la plateforme peut fonctionner conteneurisée (implémentation Docker fournie).

La plateforme applicative par défaut est la JVM. Le langage de référence est Kotlin mais d’autres langages de programmation peuvent être utilisés via les API mises à disposition.

Côté serveur, Tock utilise Vert.x et MongoDB ^{(alt. DocumentDB)}. Différentes briques NLU peuvent être utilisées, mais Tock n’a pas de dépendance forte envers l’une d’elles.

Les interfaces graphiques Tock Studio sont écrites avec Angular en Typescript.

Des intégrations React et Flutter sont fournies pour les interfaces Web et Mobile.

Structure des sources

Les dépôts

• tock : dépôt principal comprend le framework et les composants de la plateforme sous licence Apache 2.

• tock-corenlp : code utilisant une dépendance optionnelle à Stanford CoreNLP (à la place d’Apache OpenNLP), sous licence GPL.

• tock-docker : des images Docker et Docker Compose, pour faciliter la prise en main et le déploiement de la plateforme dans différentes configurations.

• tock-bot-samples : des exemples de code notamment pour programmer des parcours en mode WebHook ou WebSocket comme dans les guides Tock.

• tock-bot-open-data : un exemple de bot basé sur les API Open Data de la SNCF, implémentant également des bases pour l’internationalisation avec deux langues proposées.

Le dépôt tock

Voici une première description des sources dans le dépôt tock :

• bot : la plateforme conversationnelle (interfaces, API, connecteurs, etc.), en dépendance sur les modules NLU
• docs : le sites de documentation, générés avec MkDocs
• docs-mk : les sources pour les sites de documentation, pour MkDocs
• dokka : la documentation Dokka du framework Kotlin
• etc : des scripts utilitaires, par exemple pour générer les sites avec MkDocs
• nlp : la plateforme NLU uniquement (interfaces, API, modèles d’entités, etc.)
• scripts : d’autres scripts utilitaires, par exemple pour développer sur Messenger avec ngrok
• shared : des composants Kotlin partagés entre les différents modules du framework
• stt : des implémentations et wrappers pour le speech-to-text
• translator : des implémentations et wrappers pour le multilingue (i18n)

Remarque : il existe “deux admin” (ie. deux interfaces Tock Studio) dans les sources. En effet, il est possible d’installer la plateforme NLU / NLP seule sans les outils conversationnels. En conséquence :

• nlp/admin : contient les composants et interfaces graphiques pour le NLU / NLP seulement
• bot/admin : reprend les composants NLP / NLU (en dépendance dans le build Maven) et reconstruit les interfaces en y ajoutant les outils conversationnels

Le dépôt tock-docker

Le dépôt contient une structure de modules Maven reprenant les différents composants de la plateforme Tock. Chacun de ces modules porte une implémentation Docker du composant en s’appuie sur le plugin Maven io.fabric8:docker-maven-plugin pour encapsuler le build Docker.

A la racine du dépôt se trouvent différents descripteurs Docker Compose permettant de déployer une plateforme en se basant sur les images déjà construites. Différentes configurations existent, notamment en mode Bot API ou en mode intégré, avec la plateforme NLU standalone, etc. Le descripteur de référence pour le mode Bot API est docker-compose-bot.yml.

Build & run

Construire Tock à partir des sources

Tock (core)

Le projet est construit avec Maven, y compris les modules Web impliquant NPM et Angular :

$ mvn package

Un build d’intégration continue est disponible sur Travis.

Images Docker

Les images Docker de Tock peuvent être reconstruites à partir des sources du dépôt tock-docker. Pour cela, utilisez Maven qui déclenchera le build Docker :

$ mvn package docker:build

Vous pouvez ensuite instancier ces images via Docker ou les stacks Docker Compose avec les descripteurs à la racine du dépôt.

Exécuter dans un IDE

Pour démarrer Tock avec Docker Compose hors d’un IDE, voir Déployer Tock avec Docker.

Les différents composants Tock peuvent s’exécuter depuis un IDE (environnement de développement intégré). Des configurations sont fournies pour IntelliJ.

Voir la section Installation Tock.

Pour exécuter le bot/exemple en mode intégré, une configuration est aussi disponible : OpenDataBot.

Code

Commits & merge requests

Pour soumettre une évolution ou un correctif :

1. Créer une issue:
   • Format recommandé pour le titre :
     • [Component] Title
     • De préférence en anglais
     • Composant : par exemple Studio, Core, Doc, etc.
     • Titre : par exemple Do or fix something
2. Créer une pull request et la lier à l’issue:
   • Tous les commits doivent être signés
   • SVP rebase ou squash les commits superflus
     • Astuce : vous pouvez noter la PR comme Draft avant de la soumettre
   • Format recommandé pour le nom de la branche :
     • ISSUEID_short_title
   • Format recommandé pour le(s) message(s) de commit(s) :
     • resolves #ISSUEID Component: title pour les évolutions
     • fixes #ISSUEID Component: title pour les correctifs
3. Avant d’être intégrée, une pull request doit passer les tests et être approuvée par au moins deux de ces développeurs :
   • @vsct-jburet, @francoisno, @NainJaune, @elebescond, @SarukaUsagi, @MaximeLeFrancois, @bakic, @broxmik, @mrboizo

Conventions de code

Les Kotlin Code Conventions sont utilisées pour développer le code de Tock.

Tests unitaires

Chaque nouvelle évolution ou correctif devrait embarquer ses tests unitaires.

Nous contacter

Un problème ? Une question sur l’implémentation ? Une idée à partager ?

Pour contribuer au projet ou simplement en savoir plus, n’hésitez pas à nous contacter.