Comment contribuer

Nous acceptons le code, la documentation, les rapports de bugs et les retours de toute personne disposée à les soumettre clairement. Cette page couvre les aspects pratiques : comment faire intégrer une modification, ce que nous recherchons lors de la revue, et à quoi s’attendre après avoir ouvert une PR.

Voir Communication pour les contributions non liées au code (signalement de problèmes, retours d’expérience, obtention d’aide).

Voir le processus RFC pour les modifications importantes nécessitant une discussion de conception avant l’implémentation.

Avant de commencer

Pour toute modification autre qu’une correction de faute de frappe :

1. Consultez le suivi des problèmes. Quelqu’un travaille peut-être déjà dessus ou a ouvert une discussion liée.
2. Lisez AGENTS.md. La racine du dépôt contient le contrat compact, toujours chargé. Consultez les Directives pour les agents de codage pour des références détaillées sur les risques, la stabilité, la source de vérité et la découverte des compétences.
3. Utilisez la carte d’architecture et de contribution pour tout ce qui touche à l’architecture, la configuration, la sécurité, le workflow, la gouvernance, la CI, le comportement de publication ou la politique de contribution assistée par IA.
4. Choisissez une branche. Les PR ciblent master. Forkez le dépôt et créez une branche à partir de celle-ci ; il n’y a pas de branche develop ou integration à utiliser.

Le flux

fork → branch → commit → push → open PR → review → merge (squash)

Les points de contrôle clés :

• Modèle de PR : .github/pull_request_template.md. Complétez-le. Les sections résumé, preuves de test et compatibilité sont obligatoires.
• CI : s’exécute sur chaque PR. ci.yml est la barrière composite ; toutes les étapes doivent réussir.
• Labels : les mainteneurs utilisent les labels pour orienter le niveau de revue. Vous n’avez pas besoin de connaître chaque famille de labels avant d’ouvrir une PR. Si les labels semblent manifestement incorrects et que vous ne pouvez pas les modifier, signalez l’incohérence dans un commentaire ; les mainteneurs ou les relecteurs disposant des permissions sur les labels peuvent corriger directement les incohérences évidentes.
• Routage des revues : rendez la portée, les tickets liés, la validation et le contexte de risque/restauration suffisamment clairs pour que les relecteurs puissent choisir rapidement le bon parcours de revue.
• Revue : revue par les mainteneurs. Les constats utilisent la taxonomie de revue des PR : 🔴 bloquant, 🟡 avertissement, 🔵 suggestion, 🟢 éloge, et ✅ résolu. Traitez les points bloquants ; les avertissements doivent recevoir une réponse ; les suggestions sont facultatives.

Style de code

• cargo fmt propre (vérifié dans CI)
• cargo clippy -D warnings propre (vérifié dans CI)
• Pas de code de production inutilisé : supprimez-le, intégrez-le dans le comportement, ou créez un ticket de suivi. Ne le masquez pas avec des préfixes underscore ou #[allow(dead_code)] ; réservez les noms avec underscore aux paramètres d’API, de trait ou de callback requis mais intentionnellement inutilisés.
• Gestion des erreurs : anyhow::Result aux frontières des binaires, erreurs typées dans les crates de bibliothèque. Pas de unwrap() / expect() dans les chemins de code de production : propagez avec ? ou documentez l’invariant qui rend la panique impossible.
• Dépendances minimales : chaque dépendance augmente la taille du binaire ; pesez le pour et le contre avant d’en ajouter une
• Trait d’abord : définissez le trait dans zeroclaw-api, puis implémentez-le dans la crate edge appropriée
• Sécurité par défaut : listes d’autorisation, pas listes de blocage. Toute nouvelle surface externe est fermée par défaut
• Tests unitaires en ligne : #[cfg(test)] mod tests {} en bas du fichier ou un fichier frère tests.rs
• Ne committez pas de secrets, de données personnelles ou d’identités d’utilisateurs réels : la page Discipline de confidentialité et de PII constitue le critère de validation des merges

Commentaires et dérive

Les commentaires doivent expliquer l’intention durable, les invariants, les dangers ou la propriété du code source. N’ajoutez pas de commentaires qui reformulent le flux de contrôle adjacent, dupliquent des listes de champs de schéma ou de configuration, reflètent des variantes d’énumération, ou décrivent un comportement à l’exécution que le code et les tests n’appliquent pas. Ces commentaires deviennent des surfaces de dérive : les futurs contributeurs et outils peuvent faire confiance à la prose après que la source a changé.

Si un commentaire doit mentionner un comportement géré ailleurs, pointer vers le responsable plutôt que de le dupliquer. Privilégier les commentaires qui expliquent pourquoi une branche est sûre, quel contrat possède une règle, ou quelle source doit changer en premier.

Préférer :

• Le schéma de configuration gère les alias acceptés ; gardez ce résolveur générique.
• Cette panique est inaccessible car l'analyseur rejette les noms d'outils vides en amont.

À éviter :

• Les variantes prises en charge sont A, B et C.
• Cet indicateur active toujours la recherche vectorielle.

Si l’affirmation ne peut rester vraie qu’en modifiant manuellement le commentaire chaque fois que le code, la configuration, WIT, le schéma ou les tests changent, rendez la source plus claire ou ajoutez plutôt une référence à la source.

Tests

• Tests unitaires placés au même endroit que le code (mod tests)
• Tests d’intégration dans tests/ et tests unitaires locaux aux crates : exécutés via cargo nextest run --locked --workspace --exclude zeroclaw-desktop
• Le code conditionné par des fonctionnalités doit être testé avec des tests conditionnés par des fonctionnalités.
• Ne simulez pas la base de données pour les tests qui exercent le schéma ou le SQL : les tests d’intégration doivent utiliser une vraie base SQLite

Pour la taxonomie complète à cinq niveaux (unité / composant / intégration / système / production), l’infrastructure de simulation partagée et le format de fichier de trace JSON, consultez Testing.

Modifications de la documentation

• Les modifications de texte doivent être placées dans docs/book/src/**/*.md (ce mdBook).
• Rustdoc (///) met à jour automatiquement la référence de l’API lors du déploiement.
• Les pages de référence (docs/book/src/reference/cli.md, config.md) sont des sorties générées ignorées ; ne les modifiez pas manuellement et ne les commitez pas. Exécutez cargo mdbook refs pour prévisualiser les modifications depuis la source CLI/config propriétaire.
• Localisation : le markdown anglais est la source de vérité. Les PR de documentation anglaise courantes peuvent omettre les nombreuses modifications générées dans les fichiers .po ; utilisez la note standard de corps de PR indiquée dans Building the docs locally.
• Les PR de cache de traduction, les passes de traduction de version et les nouvelles locales doivent exécuter cargo mdbook sync, valider les fichiers .po résultants, et les vérifier avec cargo mdbook check

Publication des métadonnées du blog ou du site web

Lorsque vous publiez un article de blog ou que vous mettez à jour les métadonnées publiques du blog, mettez à jour les horodatages du flux maintenus manuellement dans la même PR :

• web/public/blog/rss.xml : définir <lastBuildDate> à la date de publication de l’article le plus récent au format RFC 2822 / GMT
• web/public/blog/atom.xml : définir <updated> sur l’heure de publication du billet le plus récent au format ISO 8601 UTC
• web/public/sitemap.xml : définir le <lastmod> de l’entrée /blog sur la date de publication la plus récente

Maintenir la découverte de flux locale à l’environnement :

• web/index.html doit conserver /blog/rss.xml, /blog/atom.xml et /sitemap.xml comme liens relatifs à la racine
• web/public/sitemap.xml doit lister la page /blog destinée aux utilisateurs, et non les fichiers de flux XML

Messages de commit

Conventional Commits :

feat(providers): add support for DeepSeek reasoning mode
fix(channels/matrix): prevent duplicate device sessions after verify
docs(getting-started): add YOLO-mode quick-start
refactor(runtime): split agent loop into steps
chore: bump tokio to 1.43

La collaboration assistée par IA est la bienvenue, mais n’ajoutez pas de mentions d’attribution bot/IA ni de pieds de page d’outils générés au corps des PR ou en fin de messages de commit. Les mentions humaines Co-authored-by: restent appropriées pour le travail des contributeurs intégré lorsqu’elles respectent les règles de remplacement et de confidentialité. Consultez FND-005 (Contribution Culture) pour la norme complète.

Demandes de tirage

Le titre reflète le commit de squash :

feat(scope): short description

Le corps du PR utilise le modèle de PR. La section test est obligatoire : expliquez comment la modification a été vérifiée, et collez les vérifications qui correspondent à la modification. La recette A/B exécutée par le relecteur sous How you can test n’est nécessaire que lorsque la vérification manuelle apporte un signal utile ; indiquez N/A pour les PR purement documentaires, les refactoring purs ou les modifications triviales sans chemin de test pertinent pour le relecteur. Pour les PRs purement documentaires, utilisez scripts/ci/docs_quality_gate.sh et scripts/ci/docs_links_gate.sh ou expliquez pourquoi la vérification des liens n’a trouvé aucun lien ajouté à inspecter. Pour les PRs Rust/code, utilisez les preuves qui correspondent à la surface modifiée : les vérifications CI obligatoires, les tests de crate ciblés ou de régression, les tests de fumée manuels, ou les vérifications de l’espace de travail complet lorsque la couverture globale prouve ce qu’une preuve plus étroite manquerait. Un CI requis récent suffit lorsqu’il couvre la surface modifiée ; un Cargo local supplémentaire n’est pas requis uniquement pour dupliquer le même HEAD, la même cible et le même jeu de fonctionnalités. Ajoutez davantage de preuves lorsque le PR dépend d’une lacune connue de la couverture CI : les tests spécifiques à une plateforme, les linters multiplateformes, la couverture des applications de bureau, les builds pour les cibles de release, les CI obsolètes ou indisponibles. « Cela fonctionne sur ma machine » n’est pas une preuve.

Les libellés de risque décrivent le changement réel et ses conséquences, et non sa portée générale. Suivez le guide des libellés des mainteneurs : risk:low désigne la documentation, les fixtures ou les métadonnées mécaniques sans effet sur la production, la compatibilité, la compilation, la publication ou la gouvernance ; risk:medium désigne les modifications comportementales ordinaires ; et risk:high désigne une frontière concrète de confiance, d’identifiants, de compatibilité, de gouvernance ou d’autorité de publication. domain:security est indépendant de risk:* et identifie une frontière de sécurité effective.

Une PR portant risk:high ou domain:security nécessite une revue approfondie, un plan de retour en arrière adapté à la modification et deux approbations indépendantes de la Core Team avant sa fusion. Utilisez risk:manual lorsqu’un mainteneur doit figer les futurs remplacements automatiques du niveau de risque ; cela ne peut pas réduire les exigences de revue.

Après la PR

Stratégie de fusion : squash-merge avec l’historique complet des commits préservé dans le corps. Consultez .claude/skills/squash-merge/SKILL.md pour le format exact : TL;DR : titre de la PR + (#number) comme sujet, liste à puces des commits originaux comme corps.

Version : les modifications sont intégrées dans master ; master ne déclenche pas automatiquement de version. Un responsable incrémente la version et crée le tag vX.Y.Z lors de la publication d’une version. Votre PR apparaîtra dans le CHANGELOG.

Domaines qui ont besoin d’aide

Code de conduite

Ne soyez pas désagréable. Soyez en désaccord avec les idées, pas avec les personnes. Acceptez que les mainteneurs ferment les sujets dont ils ne veulent pas assumer la responsabilité, généralement avec une explication, parfois sans. Si une fermeture vous semble injustifiée, posez la question ; si la question reste sans réponse, passez à autre chose.

Voir aussi

• Processus RFC : pour tout ce qui dépasse un simple correctif
• Carte d’architecture et de contribution : quels documents d’architecture, de fondations et de flux de travail lire en premier
• Communication : comment contacter l’équipe
• Mainteneurs → Vue d’ensemble : ce que font les mainteneurs au quotidien