Contribuer

Ce guide s'adresse à l'équipe interne et aux partenaires qui développent sur la base de code avec l'accord du titulaire.

À la fin de ce chapitre, vous aurez construit le workspace, lancé le backend et le frontend en local, et vous saurez quelles règles les hooks appliquent avant un commit.

Cadre

Chatbotaurus est un logiciel propriétaire. Le fichier LICENSE (identifiant SPDX LicenseRef-Chatbotaurus-Proprietary) n'accorde aucun droit d'usage, de copie, de modification ou de distribution sans accord écrit. Les dépendances tierces gardent leur propre licence. Une contribution suppose donc un accord écrit préalable ; la voie de soumission (patch, demande de fusion) est convenue avec le titulaire.

Le code est en Rust : aucune dépendance à Node.js ni à pnpm.

Prérequis

Le pre-commit lance de nombreux contrôles (.githooks/pre-commit). Sous Windows, vérifiez que python répond dans le shell du hook avant le premier commit.

Obtenir les sources et activer les hooks

git clone <url-du-depot-communiquee-par-le-titulaire>
cd <dossier-du-depot>
git config core.hooksPath .githooks

Les hooks sont versionnés avec le code (.githooks/). Le chemin ci-dessus les active ; sans lui, aucune règle n'est appliquée localement. Ne contournez jamais un hook avec --no-verify : si un hook échoue, corrigez la cause.

Construire et lancer

cargo build --workspace

La première construction est longue ; les suivantes sont incrémentales.

Le backend a besoin au minimum de DATABASE_URL, REDIS_URL et JWT_SECRET (voir Variables d'environnement). PostgreSQL et Valkey doivent tourner d'abord : créez les réseaux et les volumes, puis lancez podman-compose -p chatbotaurus-vps1 up -d postgres valkey (voir Déploiement avec Podman). Lancez ensuite le backend depuis la racine du dépôt, pour qu'il retrouve .env, connectors/ et policies/ :

cargo run -p forge-api

Résultat attendu : forge-api écoute sur le port 3000 par défaut (variable PORT) et curl -s http://localhost:3000/api/v1/healthz répond 200. Sinon, relisez la sortie du processus et suivez Problèmes connus.

Le frontend Dioxus se sert avec rechargement à chaud :

cd crates/forge-ui
dx serve --platform web --port 8080

Résultat attendu : l'application répond sur http://localhost:8080.

Vérifier

cargo check --workspace
cargo clippy --workspace
cargo fmt --all
cargo test -p <crate>

Le dépôt fige le style de rustfmt dans rustfmt.toml. Le workflow de CI (workflow de CI du dépôt) épingle un nightly daté pour cargo check et pour cargo fmt --check. Comme les autres workflows de CI du dépôt, il est dormant : aucun exécuteur n'y est rattaché. Les contrôles qui tournent aujourd'hui sont les hooks locaux.

Branche, commit et push

Le développement se fait sur la seule branche main. Le hook pre-push refuse tout push d'une autre branche, refuse un push dont cargo check --workspace échoue, et laisse passer les étiquettes.

Un message de commit suit le modèle type(portée): résumé, par exemple fix(forge-api): corriger un délai. Les types courants sont feat, fix, docs, refactor, test, chore. Le hook ne l'impose pas : c'est la convention du dépôt. Faites un commit par sujet, avec des chemins explicites (git add <fichier>), jamais git add ..

Les règles que les hooks appliquent

Le pre-commit applique aussi, entre autres : aucun emoji dans les fichiers texte, cloisonnement par organisation des handlers de liste (une exception s'annote // TENANT-AUDIT: <raison>), aucun fichier .env ajouté hors le modèle, aucun secret en clair (analyse avant chaque commit), et la règle d'auteur unique du message (commit-msg). La liste complète et les raisons sont dans docs/parity/HOOKS.md du dépôt.

Règles de code

• Pas de refactorisation dans un commit de portage : un refactor est un commit séparé.
• Pas de donnée factice inventée dans une page : les pages lisent l'API.
• Composez avec les crates existantes avant d'en créer une.
• Les composants forge-ui utilisent #[component] de Dioxus 0.7.
• Une route de liste filtre par organisation, ou porte une exception annotée et justifiée.

Règles de sécurité

• Aucun secret dans le dépôt, dans un message de commit ni dans une documentation. Utilisez des gabarits <...>. Aucune adresse IP ni nom d'hôte interne dans ce livre.
• TLS par rustls : le workspace évite OpenSSL.
• Chiffrement symétrique : aes-gcm. Mots de passe : Argon2id.
• Podman, pas Docker, pour toute infrastructure locale.
• Un connecteur doit déclarer une résidence des données dans l'UE ou auto-hébergée, sinon le registre le rejette.
• Transport MCP : HTTP « streamable » par rmcp.

Structure du dépôt

Le workspace compte 19 crates suivis par git au 2026-10-03 (git show HEAD:Cargo.toml, bloc members) ; crates/docsite est exclu.

Autres dossiers utiles : connectors/ (manifestes des connecteurs), containers/ (unités Quadlet), podman-compose.yml et podman-compose.vps2.yml (plans locaux), policies/ (règles Cedar), scripts/pre-commit/ et scripts/audit/ (les gates), .kiro/specs/ (les spécifications), docs/ (notes du dépôt).

Les chiffres du projet (crates, lignes, connecteurs) changent : mesurez-les avec python scripts/audit/launch_readiness.py plutôt que de les recopier.

Documentation

Les pages de ce livre vivent dans crates/forge-docs/docs/. Pour insérer une image ou une vidéo, voir Rédaction des pages et médias. Reconstruction : cargo run -p forge-docs.

Contact

Pour proposer une contribution, écrivez à admin@chatbotaurus.com avant de commencer.

Voir aussi

• Fichiers de configuration — les fichiers que le backend attend à la racine du dépôt
• Sécurité — protections du code que chaque contribution doit préserver
• Rédaction des pages et médias — insérer une image, une animation ou une vidéo dans ce livre
• Architecture Chatbotaurus — rôle de chaque crate et pile technique du workspace
• Déploiement avec Podman — démarrer l'infrastructure locale avec les deux plans Compose