FND-003 : Organisation de l’équipe, gouvernance du projet et pipeline de contribution

À partir de v0.7.0 · Type : Gouvernance · Rév. 16

Référence canonique · Ratifiée par l’équipe · Rév. 16 Discussion initiale sur la gouvernance : #5577 Politique de suivi des axes de travail et de gouvernance des labels : #6808

Une note à l’équipe avant que vous lisiez ceci.

Les projets logiciels n’échouent pas parce que le code est mauvais. Ils échouent parce que les personnes qui écrivent le code ne parviennent pas à se coordonner. Des fonctionnalités sont développées deux fois. Des bugs se perdent. De bonnes idées s’évaporent parce que personne ne les a notées. De nouveaux contributeurs arrivent avec l’envie d’aider et ne trouvent pas par où commencer. Cette RFC porte sur la mise en place de l’échafaudage léger qui prévient ces échecs, non pas pour que le projet paraisse organisé, mais pour que l’équipe puisse avancer plus vite, avec plus de confiance et moins de friction. Chaque recommandation présentée ici est choisie spécifiquement pour une petite équipe open source en croissance, dirigée par des étudiants. Rien ici ne nécessite de chef de projet, de Scrum Master ou de comité formel.

Historique des révisions

Table des matières

1. Le problème de coordination
2. Le système en trois parties
3. Projets GitHub : Le pipeline de travail
   • 3.6 Voies de travail et propriété de l’état
4. GitHub Discussions : discussion communautaire et transfert
   • 4.5 Gestion des discussions et transfert de Discord vers GitHub
5. Paliers d’équipe et autorité de contribution
6. CODEOWNERS et Protection des branches
   • 6.4 Conformité architecturale : revue humaine, assistance IA
7. Modèles d’incidents
8. La boucle de gouvernance des RFC
9. Taxonomie des étiquettes
10. Definition of Done
11. Automatisation
12. Déploiement progressif

1. Le problème de coordination

Chaque projet sans un système de coordination intentionnel développe un système accidentel. Le système accidentel pour la plupart des projets open source ressemble à ceci :

• Les idées résident dans la tête de quelqu’un, ou dans un message de chat qui défile hors de l’écran.
• Les problèmes s’accumulent dans le tracker sans priorité, sans propriétaire et sans définition claire de ce qui constitue un travail terminé.
• Les contributeurs ouvrent des PRs pour des choses que personne n’a demandées, ou demandent à aider et ne reçoivent aucune réponse.
• L’équipe travaille de manière réactive : celui qui crie le plus fort obtient de l’attention, ce qui tombe en panne est réparé, rien n’est planifié à plus d’une semaine
• Les décisions architecturales sont prises dans les commentaires des PR et ne sont jamais enregistrées nulle part.

Ce n’est pas une critique des efforts de qui que ce soit. C’est une description de ce qui se produit par défaut. La solution n’est pas davantage de processus. C’est le bon processus, appliqué au bon niveau selon la taille et la maturité de l’équipe.

ZeroClaw a besoin de trois choses :

1. Un pipeline pour transformer les idées en code déployé, avec des étapes visibles et des portes claires à chaque transition.
2. Un espace de discussion maintenu pour les questions de la communauté, les idées, les démonstrations et les explorations préliminaires qui ne sont pas encore prêtes pour le pipeline, sans les perdre ni encombrer le travail en cours
3. Un modèle de gouvernance qui définit qui peut décider de quoi, comment les décisions architecturales sont prises et comment l’équipe évolue.

Il s’agit de trois préoccupations distinctes. Les confondre, tout regrouper dans un seul tableau ou s’appuyer sur des discussions informelles pour les décisions, c’est précisément ce qui crée le chaos auquel l’équipe tente d’échapper.

2. Le système à trois parties

Le principe clé : le tableau de projet ne contient que le travail que l’équipe s’est engagée à étudier. Les premières discussions communautaires, les idées, les questions-réponses et les présentations peuvent vivre dans Discussions lorsque la file d’attente est maintenue. Le travail qui a été évalué, accepté et cadré vit dans le projet. C’est cette distinction qui rend le tableau utile.

FND-003 est la source de gouvernance durable pour la politique de voie de travail et de pipeline de contribution. La RFC #6808 était la discussion préparatoire pour les voies de travail orientées fonctionnalités, la gouvernance des étiquettes, le tri des tickets et le routage des mainteneurs ; après la promotion de ses tranches de politique, leurs règles durables résident dans ce document de fondation ainsi que dans les pages opérationnelles des mainteneurs liées ci-dessous. Ne traitez pas le ticket RFC comme un document de gouvernance concurrent une fois que sa politique a été promue ici.

Les détails opérationnels sont intentionnellement placés au plus près du workflow qui les utilise :

3. Projets GitHub : Le pipeline de travail

3.1 Les étapes du pipeline

Le tableau de projet possède un seul champ Statut avec sept valeurs. Chaque valeur correspond à une étape du pipeline. La séquence est linéaire, mais les éléments peuvent être déplacés vers l’arrière :

💡 Idea
    ↓  Gate: Vision alignment check
📋 Backlog
    ↓  Gate: Architecture fit + acceptance criteria
🎯 Defined
    ↓  Gate: Assignee, size, risk tier confirmed
🚧 In Progress
    ↓  Gate: Tests written, CI passing
👀 In Review
    ↓  Gate: Correct reviewer tier approved, docs updated
✅ Done

Plus un état terminal qui peut être atteint depuis n’importe où :

🚫 Won't Do  ← explicit decision not to pursue; never silently closed

L’état Won't Do au niveau du tableau est une décision de clôture durable. L’orthographe actuelle des étiquettes de clôture et les règles du processus de remplacement se trouvent dans le guide des étiquettes pour les mainteneurs et le guide de remplacement.

3.2 Les questions de la porte

Chaque transition comporte une question de validation. La question doit recevoir la réponse « oui » avant que l’élément puisse avancer. C’est le tableau de projet rendu opérationnel : la hiérarchie Vision → Architecture → Design → Implementation → Testing → Documentation devient une liste de contrôle à chaque étape.

Pourquoi les portes explicites sont importantes pour une équipe étudiante : Sans portes, les cartes avancent parce que quelqu’un estime avoir terminé, et non parce que « terminé » a une définition claire. C’est la source la plus courante de travail considéré comme « terminé » alors qu’il ne l’est pas. Les portes rendent la définition visible et partagée.

Ces questions de contrôle sont des invites de gouvernance, et non une nouvelle liste de vérification à dupliquer dans chaque description de PR ou commentaire d’issue. Les formes opérationnelles se trouvent dans les artefacts que les mainteneurs manipulent déjà :

• Les modèles de signalement collectent le rapport, la valeur utilisateur, la reproduction, l’impact sur l’architecture et les indices de risque nécessaires au premier tri ;
• le modèle de PR collecte les limites de portée, les preuves de validation, l’impact sur la sécurité/confidentialité, la compatibilité, le rollback, les labels et les tickets liés ;
• le workflow de PR du mainteneur définit la Definition of Ready, la Definition of Done, les PR lanes et les vérifications de merge ;
• le guide des étiquettes définit la classification durable, les étiquettes de politique d’obsolescence et la séquence de nettoyage ;
• Le guide du relecteur définit la prise en charge, la profondeur de relecture, le tri des problèmes, le contournement de l’automatisation et la gestion de la file d’attente.

Si une ancienne question de validation FND-003 semble manquante, vérifiez d’abord ces emplacements opérationnels avant d’en ajouter une autre copie ici.

3.3 Champs personnalisés

Créez ces champs dans les paramètres du projet GitHub :

Pour le dimensionnement (tailles de T-shirt) : Les story points nécessitent une calibration et des données historiques que l’équipe n’a pas encore. Les tailles de T-shirt sont immédiatement intuitives et suffisantes pour une équipe à ce stade :

Les éléments XL doivent presque toujours être décomposés avant qu’ils n’entrent dans la phase « En cours ». Si vous ne pouvez pas les décomposer, c’est que la conception n’est pas suffisamment aboutie.

3.4 Vues

Créez quatre vues nommées dans le projet :

Vue 1 : Feuille de route

• Type : Feuille de route (chronologie)
• Regroupé par : Jalon
• Champs visibles : Titre, Type, Taille, Composant, Assigné
• Objectif : Public. « Voici ce qui arrive et quand. » Partagez ce lien dans le README et avec la communauté. Maintenez-le à jour.

Vue 2 : Tableau

• Type : Tableau (Kanban)
• Colonnes : Valeurs du champ Statut
• Filtré pour : uniquement le jalon actuel
• Champs visibles : Titre, Assigné, Taille, Niveau de risque
• Objectif : Visibilité sur le travail quotidien. Sur quoi travaille tout le monde en ce moment ? Qui est bloqué ?

Vue 3 : Backlog

• Type : Tableau
• Trié par : Priorité (décroissant), puis Taille (croissant)
• Filtré par : Statut = Backlog OU Défini
• Champs visibles : Titre, Type, Priorité, Taille, Composant, Jalon, Niveau de risque
• Objectif : Utilisé lors des séances de préparation. Qu’est-ce qui doit être travaillé ensuite ? Qu’est-ce qui est dimensionné et prêt à être pris en charge ?

Vue 4 : Mon travail

• Type : Carte
• Filtré par : Assigné = @moi
• Objectif : Tableau de bord personnel. Chaque contributeur peut voir ses propres éléments sans bruit.

3.5 Éléments épinglés

GitHub permet jusqu’à six éléments épinglés par dépôt. Utilisez-les pour une communication à fort signal, toujours visible :

1. Le RFC actuellement actif en cours de discussion
2. La fonctionnalité communautaire la plus demandée (Discussion la plus votée)
3. Le prochain jalon de version suivi par ce problème
4. L’index des bonnes premières tâches (une issue qui renvoie vers tous les éléments good first issue actuels)

Les problèmes épinglés sont une promesse faite à la communauté : ce sont les éléments qui comptent le plus en ce moment. Mettez-les à jour lorsque les priorités changent.

3.6 Voies de travail et propriété de l’état

La politique de couloir de travail empêche le tableau, les labels, PRs et issues de tenter de répondre à la même question à différents endroits.

Utilisez cette répartition :

Les couloirs de PR, les libellés contributor-pickup, les libellés stale-exemption et la migration des libellés sont des concepts de gouvernance durables, mais leurs critères opérationnels précis figurent dans la documentation des mainteneurs. FND-003 régit la répartition : les libellés classifient le travail durable, les tableaux de projet planifient le travail, l’état natif des PR gère l’état actif de revue et de fusion, et les issues/RFC conservent les décisions. Le workflow de PR des mainteneurs régit les définitions des couloirs de PR, le guide des libellés régit la signification exacte des libellés et les règles de nettoyage, et le manuel du relecteur régit la façon dont les relecteurs appliquent ces signaux lors du tri et de la revue. Traitez la migration active des libellés comme un nettoyage distinct approuvé par les mainteneurs, et non comme une revue de PR ordinaire.

Les exemptions d’obsolescence sont des exceptions de gouvernance, et non des boucliers permanents sous forme d’étiquettes. La politique cible veut que status:no-stale ne soit valide que lorsque la source opérationnelle de la voie enregistre la raison de l’exemption de l’issue ainsi que les preuves de routage visibles qui portent la prochaine décision. La documentation des mainteneurs définit où ces informations résident et comment l’automatisation d’obsolescence ou les balayages d’obsolescence appliquent la règle.

4. GitHub Discussions : Discussion communautaire et transfert

4.1 Voie des discussions maintenues

Considérez GitHub Discussions comme un espace communautaire maintenu. Les discussions sont utiles pour les questions, les idées, les sondages, les annonces, les vitrines, les démos de projets ou d’intégrations, ainsi que pour les fils de discussion exploratoires qui nécessitent plus de permanence que Discord, mais qui ne correspondent pas encore à un travail suivi.

Les catégories exactes, les descriptions de catégories et la fréquence de revue sont des détails opérationnels. Ils relèvent du guide de communication des contributeurs et de la documentation des flux de travail des mainteneurs, et ils peuvent évoluer sans nécessiter de révision de ce document fondateur.

4.2 Passage de la discussion au travail suivi

Les discussions ne deviennent pas des tâches du backlog simplement parce qu’un fil existe. Promouvez une discussion lorsqu’elle produit un résultat concret et suivi. Des exemples de déclencheurs destinés aux contributeurs se trouvent dans Communication.

La cible dépend du résultat. Les bugs confirmés et les périmètres de fonctionnalités acceptés deviennent des issues. Les décisions d’architecture passent par le processus RFC. Les détails spécifiques à une PR sont déplacés vers les commentaires de la PR. Les règles de fonctionnement pérennes sont déplacées vers la documentation des mainteneurs ou des contributeurs.

Bouclez la boucle dans la Discussion d’origine. Si la catégorie prend en charge les réponses, marquez le résumé ou le lien du travail suivi comme réponse lorsque cela est approprié. Sinon, ajoutez un commentaire de résumé final avec le lien de l’issue, de la RFC, de la PR ou de la documentation.

4.3 Idées qui ne devraient pas attendre les votes

Certains éléments contournent les Discussions et entrent directement dans la surface suivie :

• Vulnérabilités de sécurité (via un rapport de sécurité privé, jamais public)
• Bugs confirmés avec des étapes de reproduction (accédez directement au modèle de rapport de bug)
• Éléments d’architecture acceptés par la RFC (générés directement à partir de la boucle de clôture de la RFC)
• Éléments du calendrier du projet (ajoutés directement par l’équipe principale)

4.4 Exploration de l’architecture

L’exploration d’architecture peut commencer dans les Discussions lorsque la question concerne la communauté et n’est pas encore prête pour une RFC formelle. Cela abaisse la barrière à l’expression de préoccupations de conception sans transformer chaque réflexion préliminaire en politique suivie.

Lorsque le fil de discussion aboutit à une proposition d’architecture concrète, ouvrez l’issue RFC et déplacez la proposition durable vers la surface RFC. La Discussion peut alors créer un lien vers la RFC et cesser d’être la source de vérité.

4.5 Gestion des discussions et transfert de Discord vers GitHub

Discord est destiné aux conversations rapides. GitHub constitue l’enregistrement durable. Les Discussions sont une surface GitHub maintenue pour les échanges avec la communauté qui nécessitent plus de permanence que Discord mais qui ne constituent pas encore un travail suivi.

Les Discussions ne sont actives que lorsque quelqu’un prend en charge le canal. Cette prise en charge peut être assurée par un responsable désigné ou par une cadence de revue documentée. Sans prise en charge, les Discussions constituent une archive passive, et non un point d’entrée obligatoire.

Utilisez les Discussions pour les fils de discussion exploratoires, communautaires ou nécessitant un retour large. Utilisez une issue, une RFC issue, un commentaire de PR ou un document de mainteneur lorsque le résultat est déjà concret ou fait autorité. La liste des déclencheurs destinés aux contributeurs ainsi que des exemples de catégories se trouvent dans Communication.

Le handoff n’a pas besoin de copier l’intégralité de la conversation. Capturez le résultat et suffisamment de contexte pour qu’un autre mainteneur puisse continuer. Si une Discussion produit ultérieurement un travail suivi ou une politique durable, promouvez ce résultat dans la surface qui en est responsable.

5. Niveaux d’équipe et autorité de contribution

5.1 Les trois niveaux

Les projets open source fonctionnent selon la méritocratie : l’influence et l’autorité découlent des contributions démontrées, et non de l’ancienneté, du titre ou des relations personnelles. C’est l’une des choses qui distinguent l’open source du logiciel d’entreprise, et cela mérite d’être enseigné explicitement.

Les trois niveaux reflètent un engagement croissant envers le projet :

Niveau 1 : Communauté

Tout le monde. Aucune approbation requise.

Ce qu’ils peuvent faire :

• Ouvrir des problèmes en utilisant les modèles de problème
• Commentez sur n’importe quelle issue ou PR
• Réagissez aux discussions et votez pour les idées
• Soumettez des pull requests (qui seront examinées avant la fusion)
• Modifier le Wiki GitHub

Ce qu’ils ne peuvent pas faire :

• Être assigné des tâches (peut demander à être assigné)
• Approuver les PR
• Fusionner les PR
• Votez sur les RFCs ayant une autorité contraignante

Niveau 2 : Contributeur

Les membres de la communauté qui ont eu au moins deux PR fusionnées dans la branche master.

Comment le devenir : Faire fusionner deux PR, reconnues par un membre de la Core Team. Le niveau 2 ne dispose aujourd’hui d’aucun enregistrement d’adhésion durable ; voir §5.3.

Ce qu’ils gagnent au-delà de la communauté :

• Peut être assigné des tâches
• Peut être demandé comme réviseur sur les PRs (révision non obligatoire)
• Les votes sur les idées dans les discussions comptent pour le seuil de promotion.
• Peut demander des discussions RFC sans passer par Discussions en premier

Ce qu’ils ne peuvent toujours pas faire :

• Approuvez les PR pour les chemins à haut risque
• Fusionner les PR
• Exprimer les votes pour les propositions RFC

Pourquoi ce niveau existe-t-il : Il établit un premier objectif visible et atteignable pour les nouveaux contributeurs. « Comment puis-je m’impliquer davantage ? » a une réponse claire : obtenir deux PR fusionnées. Cela motive les premières contributions de qualité et offre à l’équipe un moyen de reconnaître publiquement les contributeurs.

Niveau 3 : Équipe principale

Les contributeurs qui ont démontré des contributions constantes et de haute qualité au fil du temps et qui ont été invités par des membres existants de l’équipe principale.

Comment le devenir : Sur invitation des membres actuels de la Core Team, annoncée publiquement dans les Discussions. Il n’existe pas de seuil formel ; il s’agit d’une décision discrétionnaire fondée sur la qualité, la régularité et la cohérence des contributions passées.

Ce qu’ils gagnent au-delà de Contributor :

• Accès en écriture au dépôt
• Peut fusionner les PR qui ont satisfait aux exigences de revue.
• Peut approuver les PR pour les chemins à haut risque (sous réserve des exigences de CODEOWNERS)
• Exprimer des votes sur les RFC
• Peut déplacer des éléments à travers le pipeline du projet
• Peut couper les versions
• Participer aux décisions de gouvernance (discussions de l’équipe principale)

Résponsabilités :

• Triagez les nouveaux problèmes dans un délai de 3 jours ouvrables.
• Examinez les PR dans leur domaine d’expertise dans les 5 jours ouvrables.
• Participer aux votes des RFC
• Respectez le Code de conduite du projet

5.2 La règle du consensus paresseux

Pour les décisions de routine, ajouter une étiquette, fermer une issue obsolète, mettre à jour la documentation, les membres de la Core Team fonctionnent selon le principe du consensus tacite : si vous annoncez votre intention dans l’issue concernée et qu’aucun membre de la Core Team ne s’y oppose dans les 48 heures, vous pouvez procéder. Cela évite la paralysie qu’entraînerait l’exigence d’une approbation explicite pour chaque action, tout en maintenant la visibilité.

Le consensus paresseux ne s’applique pas à :

• Acceptation ou rejet de la RFC
• Releases
• Modifications apportées aux fichiers CODEOWNERS ou aux règles de protection des branches
• Modifications apportées à ce document de gouvernance
• Ajouts à l’équipe principale

Ces éléments nécessitent toujours des votes explicites de l’équipe Core.

5.3 Enregistrement de l’appartenance à l’équipe

L’appartenance elle-même est établie par décision, et non par un fichier ou un paramètre GitHub. Conformément au §5.1, quelqu’un devient membre de la Core Team par invitation des membres existants de la Core Team, annoncée publiquement dans les Discussions. Cette décision, et son annonce publique, constitue la source de vérité. Tout ce qui suit est l’enregistrement d’un élément en aval de celle-ci, et aucun d’eux n’est un registre des membres :

L’équipe GitHub core-contributors et la liste des collaborateurs du dépôt, dans les paramètres de l’organisation : contrôles d’accès, pas registres d’appartenance. Ils indiquent qui dispose d’un accès en écriture au dépôt, ce qui est une conséquence de l’appartenance plutôt qu’une définition de celle-ci. Attendez-vous à ce qu’ils diffèrent de la liste des membres dans les deux sens. Ils incluent des comptes d’automatisation qui ne sont pas des personnes, et l’accès peut être accordé directement, conservé depuis avant une décision d’appartenance, ou encore en attente d’acceptation d’une invitation. Lorsque vous devez savoir qui peut push, consultez-les. Lorsque vous devez savoir qui fait partie de la Core Team, consultez l’annonce qui l’a admis.

.github/CODEOWNERS à la racine du dépôt : routage des révisions, pas appartenance. Il indique qui est sollicité pour quels chemins. Y figurer ne confère pas l’appartenance, et être membre n’implique pas d’y figurer. Toute modification de ce fichier requiert un vote explicite de la Core Team, conformément au §5.2.

Le tableau des mainteneurs dans Communication : le résumé lisible par un humain des membres actuels et des sujets sur lesquels chacun travaille. C’est ce qui se rapproche le plus d’une liste publiée, et il est maintenu à la main, alors traitez-le comme un résumé des décisions d’admission plutôt que comme une autorité. Pour les domaines d’intervention, c’est une vue pratique de CODEOWNERS, et en cas de désaccord entre les deux, CODEOWNERS l’emporte.

Les retraits fonctionnent de la même manière que les admissions : ce sont des décisions, consignées là où elles sont prises. Révoquer l’accès ou retirer quelqu’un de CODEOWNERS met en œuvre un départ ; cela ne constitue pas en soi un départ.

Les révisions 1 à 7 de ce document spécifiaient un fichier CONTRIBUTORS.md à la racine du dépôt en tant qu’enregistrement d’adhésion organisé par niveaux, et nommaient les équipes GitHub zeroclaw-core et zeroclaw-contributors. Aucun des trois n’a jamais été créé ; l’organisation utilise à la place une seule équipe core-contributors. La RFC #6808 est parvenue indépendamment à la même conclusion, en consignant que la structure de niveaux d’équipes FND-003 ne correspond pas au modèle de routage actuel visible et que de nouvelles règles de voie ne devraient pas y être adossées. Ces références sont retirées ici plutôt que laissées comme description d’un mécanisme qui n’existe pas.

Le niveau 2 ne dispose actuellement d’aucun enregistrement d’appartenance durable. L’établissement d’un tel enregistrement, ou la suppression du niveau, est une question ouverte pour l’équipe.

6. CODEOWNERS et protection des branches

6.1 CODEOWNERS

Le fichier CODEOWNERS rend la gouvernance automatique. Il définit quels chemins nécessitent une revue de quelle équipe avant qu’une PR puisse être fusionnée. GitHub applique cela comme une revue obligatoire : la PR ne peut pas être fusionnée tant que l’exigence n’est pas satisfaite.

Le bloc ci-dessous est la proposition illustrative d’origine, conservée pour le raisonnement qu’elle expose concernant le routage des revues protégées. Il ne s’agit pas du fichier actuel et il ne doit pas être copié. .github/CODEOWNERS existe déjà et est activement maintenu ; il achemine les demandes vers des handles individuels plutôt que vers des handles d’équipe, et ses chemins suivent l’organisation des crates post-microkernel établie dans #6537. Les handles @zeroclaw-labs/zeroclaw-core et @zeroclaw-labs/zeroclaw-contributors utilisés ici n’ont jamais été créés ; voir §5.3. Ses chemins de routage généraux ne correspondent pas au classifieur risk:high actuel ; consultez le fichier en vigueur et le guide des labels pour les mainteneurs pour connaître le routage actuel et la sémantique des risques.

# CODEOWNERS — Automatic review routing by protected surface
# See the maintainer label guide for risk definitions.
# See the governance foundation doc and RFC issue template for team tier definitions.

# ── Protected review routing: Core Team review ──────────────────────────────

src/security/**                 @zeroclaw-labs/zeroclaw-core
src/gateway/**                  @zeroclaw-labs/zeroclaw-core
src/runtime/**                  @zeroclaw-labs/zeroclaw-core
src/tools/shell.rs              @zeroclaw-labs/zeroclaw-core
src/tools/file_write.rs         @zeroclaw-labs/zeroclaw-core
src/tools/security_ops.rs       @zeroclaw-labs/zeroclaw-core

# ── Governance and configuration: requires Core Team approval ───────────────

.github/**                      @zeroclaw-labs/zeroclaw-core
CODEOWNERS                      @zeroclaw-labs/zeroclaw-core
Cargo.toml                      @zeroclaw-labs/zeroclaw-core
deny.toml                       @zeroclaw-labs/zeroclaw-core

# ── Architecture documents: requires Core Team review ───────────────────────

docs/book/src/foundations/**    @zeroclaw-labs/zeroclaw-core
docs/book/src/architecture/decisions/**  @zeroclaw-labs/zeroclaw-core
AGENTS.md                       @zeroclaw-labs/zeroclaw-core

# ── Default: any Contributor or Core Team member can review ─────────────────

*                               @zeroclaw-labs/zeroclaw-contributors

À mesure que des membres spécifiques de la Core Team prennent en charge des composants, ajoutez leurs identifiants individuels aux côtés de l’identifiant de l’équipe. La spécificité l’emporte dans CODEOWNERS : une règle de chemin plus spécifique prévaut sur une règle plus générale.

6.2 Règles de protection des branches

Configurez les règles de protection de branche suivantes pour master :

Pourquoi les administrateurs ne peuvent pas contourner : L’une des erreurs les plus courantes dans les projets de petites équipes est de considérer la protection des branches comme « pour les autres ». Quand un administrateur peut contourner les règles, il le fera, sous la pression du temps, en cas d’urgence, « juste cette fois ». Puis cela devient la norme. La règle doit s’appliquer à tout le monde pour avoir un sens. S’il y a une véritable urgence, la bonne réponse est de suivre le processus plus rapidement, pas de le sauter.

Le nombre d’approbations natif de GitHub est configuré par branche protégée ou cible d’ensemble de règles, et non de manière conditionnelle selon l’étiquette de la PR. Tant qu’une conception technique de mise en œuvre, approuvée séparément, ne fournit pas de source d’autorité lisible par machine pour l’approbation de Core Team, les responsables de maintenance doivent appliquer l’exigence risk:high OR domain:security au moyen de la checklist de fusion documentée et conserver une trace de revue auditable. risk:manual bloque uniquement tout remplacement automatique ultérieur du risque ; il ne peut pas réduire cette exigence.

6.3 Vérifications d’état requises

Les vérifications CI qui doivent réussir avant qu’une PR puisse être fusionnée :

build (stable)          ← cargo build --release
test                    ← cargo test
fmt                     ← cargo fmt --all -- --check
clippy                  ← cargo clippy --all-targets -- -D warnings

À mesure que l’espace de travail se décompose en crates (conformément à la RFC sur l’architecture), ajoutez des vérifications par crate. Une modification dans crates/zeroclaw-api doit exécuter la suite de tests de cette crate de manière indépendante.

6.4 Conformité architecturale : revue humaine, assistance IA

Cette section existe parce que la question se posera (elle s’est déjà posée) et qu’elle mérite une réponse claire et documentée plutôt qu’un débat à chaque PR.

La question : Devrions-nous ajouter un filtre automatisé qui vérifie si une PR est conforme à l’architecture et aux modèles de conception définis dans les RFC ?

La réponse : Non. Et comprendre pourquoi est important.

Il existe deux types fondamentalement différents de contrôle de la qualité, et ils nécessitent des mécanismes différents.

Le premier type est la conformité structurelle : ce code enfreint-il une règle mécanique ? zeroclaw-kernel importe-t-il TelegramChannel ? Les arêtes du graphe de dépendances pointent-elles dans la mauvaise direction ? Y a-t-il des avertissements de clippy ? Il s’agit de questions binaires. Soit le code enfreint la règle, soit il ne l’enfreint pas. Le compilateur, cargo deny et cargo clippy --workspace imposent déjà cette conformité. Aucun humain n’est nécessaire. Aucune IA n’est nécessaire. La machine est autoritaire, rapide et ne se trompe jamais sur une violation factuelle.

Le deuxième type est l’intention architecturale : cette décision a-t-elle sa place ici ? Cette abstraction se situe-t-elle à la bonne couche ? Ce compromis est-il aligné avec la vision ? Ce couplage sera-t-il douloureux en Phase 3 ? Cette PR créera-t-elle une charge de maintenance qui n’est pas visible dans le diff aujourd’hui ? Ces questions exigent du jugement, du contexte et une compréhension du pourquoi de l’architecture, pas seulement des règles. Aucun outil automatisé ne peut y répondre de manière fiable, car la réponse dépend d’informations qui ne figurent pas dans le diff : la feuille de route, les priorités actuelles de l’équipe, l’intention du contributeur et le coût à long terme de la décision.

Les modes de défaillance de l’automatisation du jugement architectural sont tous deux problématiques.

Un portail de validation qui laisse passer des violations architecturales subtiles crée une fausse confiance. Le développeur voit ✅ et suppose que sa décision a été validée. La dérive architecturale la plus dommageable, celle qui prend des années à démêler, semble structurellement correcte. Elle compile. Elle passe le lint. Le graphe de dépendances est correct. Le problème est qu’elle a violé l’esprit de la conception d’une manière qui ne devient apparente que plus tard, lorsque le coût pour la défaire est élevé.

Une porte qui signale des décisions architecturales valides parce que l’outil a mal interprété le contexte apprend aux développeurs à ignorer complètement cette porte. Une fois qu’une équipe a appris à cliquer au-delà d’un contrôle automatisé bruyant, ce contrôle devient inefficace en pratique, même s’il est toujours exécuté dans CI. Le projet a dépensé des minutes CI pour obtenir une valeur négative.

CODEOWNERS est la porte de conformité architecturale. Le réviseur est l’outil.

La configuration CODEOWNERS de la §6.1 achemine déjà des périmètres de revue protégés tels que les frontières de crates, les définitions de traits, le graphe des dépendances, src/security/ et .github/ vers un relecteur de la Core Team. Cette attribution est distincte de la classification risk:*. Le relecteur de la Core Team, s’appuyant sur les RFC comme cadre de référence, constitue le contrôle de conformité architecturale. Il apporte le discernement contextuel qu’aucune automatisation ne peut reproduire.

C’est pourquoi les RFC, les fichiers AGENTS.md et les normes de documentation existent : non pas pour qu’une machine puisse les analyser et produire un score, mais pour qu’un réviseur humain dispose d’un cadre cohérent et documenté à appliquer. La RFC répond à la question « pourquoi cette architecture existe-t-elle ? ». Le réviseur répond à la question « cette PR sert-elle ou affaiblit-elle cet objectif ? ».

L’IA doit faire partie du cycle de développement, pas de la porte de fusion.

Les outils d’IA, Claude, Copilot, Cursor, et tout ce qui viendra ensuite, sont véritablement utiles pour le travail d’architecture lorsqu’ils sont utilisés au bon endroit. Le bon endroit, c’est pendant le développement, pas au moment de la validation de la fusion.

Pendant le développement, un assistant IA équipé de la RFC et du fichier AGENTS.md du crate peut aider un contributeur à comprendre dans quel crate une nouvelle fonctionnalité doit être intégrée avant même de la coder, signaler une inversion potentielle de dépendance pendant que le code est encore en cours de conception, expliquer pourquoi un motif de conception existe, et suggérer si une nouvelle abstraction se situe au bon niveau. Cela constitue une amélioration additive. Cela rend les contributeurs plus compétents.

Lors d’une revue, un assistant IA peut aider un réviseur humain à rédiger des commentaires structurés, à croiser une modification avec la RFC et à identifier les questions de discussion de la RFC pertinentes pour la PR. Cette approche est également additive. Le réviseur apporte son jugement ; l’IA apporte rapidité et mémoire.

Ce que l’IA ne peut pas faire, c’est remplacer le jugement. « L’IA m’aide à évaluer cette PR » et « L’IA valide automatiquement cette PR » sont catégoriquement différents, et seul le premier fonctionne pour les décisions architecturales. Le jour où le projet fait passer la conformité architecturale par un portail automatisé, aussi sophistiqué soit-il, est le jour où l’architecture commence à dériver d’une manière que personne ne remarque jusqu’à ce qu’il soit trop tard.

La politique pratique, énoncée clairement :

• La conformité structurelle (direction d’importation, graphe de dépendances, lint, format) est imposée par CI. Cela est non négociable et automatisé.
• La conformité à l’intention architecturale est assurée par le routage via CODEOWNERS vers un réviseur de l’équipe Core. Cela est non négociable et manuel.
• Les outils d’IA accompagnent les contributeurs pendant le développement et aident les relecteurs lors de la revue. Ils ne bloquent pas les fusions par leur propre autorité.
• Si l’équipe souhaite évaluer des outils de revue assistés par l’IA à l’avenir, cette évaluation doit d’abord passer par le processus RFC. Elle ne sera pas ajoutée à .github/workflows/ sans une décision documentée.

Cette politique ne constitue pas une limitation de l’IA ou de l’automatisation. Elle reconnaît que différents problèmes nécessitent des outils différents, et utiliser le bon outil au bon endroit est exactement ce que la RFC d’architecture demande au codebase.

7. Modèles d’émission

Les modèles d’issue redirigent les rapports entrants vers le bon processus avant qu’ils n’atteignent un humain. Un modèle bien rédigé recueille automatiquement les informations nécessaires au tri. Un modèle manquant ou ignoré entraîne des issues qui nécessitent trois échanges de commentaires pour être comprises.

La source de vérité opérationnelle est .github/ISSUE_TEMPLATE/. Ne dupliquez pas ici le YAML complet du template. Lorsque la formulation du template change, mettez à jour le formulaire d’issue lui-même et conservez cette section au niveau de l’intention durable.

Voies d’admission actuelles :

Les vulnérabilités de sécurité ne disposent pas de modèle d’issue public. config.yml renvoie vers la politique de sécurité privée, Discord, GitHub Discussions, le guide de contribution, le processus RFC et le workflow de PR des mainteneurs, afin que les contributeurs puissent choisir le bon canal avant de créer une issue suivie.

Les modèles de tickets recueillent des éléments factuels ; ils ne déterminent pas les libellés finaux par eux-mêmes. Les mainteneurs continuent d’appliquer des libellés relevant du jugement uniquement, tels que status:accepted, status:no-stale, help wanted et good first issue, après avoir examiné le corps, la discussion et le travail lié. En particulier, status:no-stale ne doit pas être appliqué automatiquement à partir d’un modèle. Un tracker, une RFC ou un ticket accepté de longue durée doit consigner à la fois la raison de l’exemption de péremption et la prochaine décision ou surface de réexamen visible avant que la protection contre la péremption ne soit ajoutée ou maintenue.

8. La boucle de gouvernance RFC

Le processus RFC a été établi dans la RFC sur la documentation et la RFC sur l’architecture. Cette section définit la boucle de clôture : comment une RFC passe de la proposition à la décision, puis à l’action.

Lorsqu’un RFC est requis. Un RFC consigne une décision durable à l’échelle du projet avant sa mise en œuvre. Exigez-en un lorsque la proposition répond à au moins l’un des critères suivants :

• une nouvelle couche de sécurité, ou une modification substantielle du modèle de sécurité du projet ;
• une modification de la gouvernance, du processus de contribution ou de l’autorité du projet ;
• une refactorisation architecturale transversale qui modifie la responsabilité ou les contrats entre des frontières établies ; ou
• un nouveau sous-système ou une autre frontière de capacité à l’échelle du projet.

N’exigez pas de RFC simplement parce que le travail comprend l’ajout d’une fonctionnalité ordinaire, une migration de schéma ou de données, une modification d’un champ de configuration ou d’une valeur par défaut, ou une refactorisation limitée. Ces changements passent par une issue et une PR. Ils nécessitent un RFC uniquement lorsque leur effet substantiel satisfait également à l’un des critères ci-dessus.

Le déclenchement est déterminé par l’impact substantiel sur le projet, et non par le titre de l’issue, son auteur, son origine assistée par IA ou la simple présence d’une migration, d’une fonctionnalité ou d’une modification par défaut. Les vulnérabilités de sécurité doivent être signalées en privé, jamais dans une RFC publique.

Les mainteneurs peuvent modifier les étiquettes d’une RFC déposée ou la fermer en tant que problème ordinaire, demande de fonctionnalité ou suivi de l’implémentation lorsqu’elle ne remplit pas la condition de déclenchement. La décision indique si le travail sous-jacent reste valide et où il se poursuit. Cela permet d’orienter le travail ; il ne s’agit pas d’un rejet sur le fond.

8.1 Le cycle de vie complet de la RFC

Les révisions et clarifications ordinaires apportées par l’auteur au cours de la discussion ne relancent pas le délai. Une révision qui modifie substantiellement la décision proposée établit un nouvel instantané stable, identifié publiquement, et relance la période minimale de discussion applicable.

1. AUTHOR opens an RFC issue using the RFC issue template,
   naming the trigger the proposal crosses
           |
2. DISCUSSION PERIOD, against a visible proposal
     minimum 48 hours for an ordinary RFC
     minimum 72 hours when the exceptional unanimous path is requested
   Anyone can comment. Core Team members engage substantively.
           |
3. VOTE OPENS once the period has elapsed and the proposal is stable.
   The vote-opening comment records:
     - the immutable proposal snapshot (artifact, commit, or issue-body digest)
     - the assigned active electorate, and inactive Core notified for re-entry
     - the threshold, and why it applies
     - that quorum requires two explicit ballots
     - the exact UTC deadline, 72 hours after opening
           |
4. CORE TEAM BALLOTS, one of:
     APPROVE  accept the snapshot as written
     REVISE   request changes, withhold approval, do not veto
     REJECT   blocking objection, with a specific reason
   A member's latest ballot before the deadline supersedes their earlier one.
           |
5. OUTCOME, applied in this precedence order:
     a. Fewer than two explicit ballots        -> DEFERRED
     b. Quorum met and any final ballot REJECT -> REJECTED
     c. Quorum met, no REJECT, two-thirds
        approving explicitly or by silence     -> ACCEPTED
     d. Otherwise                              -> RETURNED TO DISCUSSION

Les RFC acceptées portent status:accepted, et le compte rendu de clôture traite chaque objection REVISE au lieu de l’écarter. Les RFC rejetées sont clôturées avec l’objection bloquante consignée et un lien vers tout ticket où le problème sous-jacent persiste ; le rejet met fin à la proposition actuelle, mais pas nécessairement au problème. Les propositions reportées restent ouvertes, avec la condition requise pour un autre vote consignée, et une proposition reportée inchangée peut faire l’objet d’un nouveau vote de 72 heures sans reprendre la discussion.

Utilisez les libellés type:rfc et status:accepted actifs. Il n’existe pas de famille parallèle de libellés d’état rfc:*.

La révision 15 s’applique aux votes sur les RFC ouverts après la ratification. Elle n’invalide pas automatiquement les RFC acceptées antérieurement ; les travaux d’audit et de correction du processus historique continuent d’être suivis séparément.

Un vote ne peut être clôturé de manière anticipée que lorsque chaque membre de l’électorat actif final a explicitement donné son approbation et qu’aucun contributeur Core par ailleurs inactif n’a demandé que la période complète soit respectée. Le compte rendu de clôture doit indiquer pourquoi il a été clôturé avant la date limite. Un vote unanime exceptionnel ne peut être clôturé de manière anticipée qu’avec l’approbation explicite de chaque électeur désigné.

8.2 Seuils de vote

Le seuil par défaut correspond aux deux tiers de l’électorat actif final, arrondis à l’électeur supérieur. L’électorat actif final est constitué de l’électorat attribué à l’ouverture, auquel s’ajoute tout autre membre actuel de Core Team qui vote lors de ce même scrutin.

• Quorum nécessite qu’au moins deux contributeurs actuels de Core expriment explicitement leur vote. Le silence ne compte jamais pour atteindre le quorum.
• Le silence vaut APPROVE de la part de l’électorat actif final une fois le quorum atteint, uniquement pour les votes ordinaires.
• REVISE est considéré comme une non-approbation et n’a pas de droit de veto.
• REJECT oppose son veto à l’acceptation une fois le quorum atteint.

Par exemple, avec quatre membres dans l’électorat actif final, un APPROVE explicite, un REVISE explicite et deux membres silencieux produisent trois approbations sur quatre, ce qui atteint le seuil.

L’unanimité est réservée aux décisions dont le coût ou l’irréversibilité rend l’approbation à la majorité qualifiée insuffisante, comme les modifications de licence ou de propriété juridique. L’ouverture du vote doit expliquer pourquoi l’unanimité s’applique. Un vote à l’unanimité requiert un APPROVE explicite de chaque contributeur Core éligible et assigné ; le silence ne peut pas établir l’unanimité.

Électorat actif. Un contributeur Core actif est un membre actuel de la Core Team qui a émis un bulletin APPROVE, REVISE ou REJECT explicite lors d’un vote RFC officiellement ouvert au cours des 30 jours précédents, et qui ne s’est pas publiquement retiré ni n’a signalé son indisponibilité pour la période de vote. Les membres actuels inactifs de la Core Team en sont informés et peuvent rejoindre l’électorat final d’un vote en y votant, ce qui les réactive également pour les votes ultérieurs.

Le quorum et le dénominateur sont déterminés séparément pour chaque vote. L’activité est vérifiée lors de l’ouverture du vote ; une activité ultérieure dans le cadre d’un autre vote concurrent ne modifie pas l’électorat d’un vote déjà ouvert.

8.2a Décisions de la réunion centrale et le GitHub Bridge

GitHub est la source de vérité pour le texte des propositions, les discussions, l’ouverture des votes, les bulletins de vote, les échéances et les résultats. Discord peut annoncer un RFC ou en discuter, mais n’établit pas l’état de la gouvernance.

Les décisions des réunions des contributeurs principaux, consignées dans le document de décision interne approuvé du projet, peuvent guider l’action immédiate des mainteneurs et primer sur les directives internes antérieures. Toute action de ce type qui modifie l’état public du projet doit laisser une trace de liaison GitHub dans l’issue, la PR, l’outil de suivi ou la RFC concerné. Cette trace indique la date de la réunion ou le document de décision, résume la décision appliquée, précise l’action publique effectuée et indique s’il s’agit d’une exception ponctuelle ou d’une modification durable des règles.

Les décisions prises en réunion ne réécrivent pas silencieusement ce document, la documentation destinée aux contributeurs, les libellés, les modèles d’issues ou les résultats des RFC. Les changements durables de gouvernance ne deviennent une politique que lorsqu’ils sont reflétés dans les espaces GitHub et la documentation pertinents. Pour les décisions unanimes exceptionnelles, un compte rendu de réunion interne ne peut remplacer les approbations explicites requises sur GitHub, à moins que ce compte rendu documente les membres ayant approuvé et que l’issue publique consigne ce fondement.

8.3 Suivi durable et lien avec les ADR

Pour les RFC nouvellement acceptées, la forme finale et le suivi durable doivent être visibles depuis l’issue de la RFC avant que l’implémentation ne se poursuive. L’acceptation seule ne complète pas le transfert de gouvernance. Pour les RFC acceptées auditées après l’implémentation, consignez la disposition de manière rétrospective sans rouvrir un travail déjà terminé.

Chaque enregistrement de décision identifie la forme finale faisant autorité, la disposition retenue et sa justification, l’artefact durable ou le suivi de livraison, ainsi que le responsable ou la prochaine action lorsqu’un suivi s’impose.

Utilisez l’une des quatre dispositions :

• ADR : requis lorsque la décision contraint de manière significative l’architecture future. Les indicateurs incluent une frontière de système surprenante, un compromis non évident ou un choix qui limite de manière significative les alternatives d’architecture futures.
• Mise à jour d’un document permanent : requise lorsque le résultat durable est un contrat opérationnel, de référence, de flux de travail, de sécurité ou utilisateur plutôt qu’une nouvelle décision d’architecture.
• Suivi de la mise en œuvre ou du tracker : requis lorsqu’un ADR, un FND ou un document permanent existant contient déjà la décision et que le travail de livraison reste à faire. Liez le tracker de livraison et sa prochaine action.
• Aucun artefact distinct : autorisé lorsqu’un FND, une ADR, un document permanent, une implémentation terminée ou une décision de remplacement déjà identifié préserve le résultat et qu’aucun suivi de livraison supplémentaire ne subsiste. Le ticket doit consigner cette justification et créer un lien vers la surface durable.

Un RFC est le support de discussion et d’acceptation. Un ADR est l’enregistrement permanent d’une décision d’architecture significative, et non un résumé obligatoire de chaque RFC accepté. Les documents permanents et les tableaux de suivi d’implémentation ne remplacent pas un ADR lorsque la décision acceptée atteint le seuil d’architecture défini ci-dessus.

8.4 RFCs fondamentaux

Les documents de proposition initiaux ont depuis été représentés sous forme d’issues RFC et de documents de fondation :

9. Taxonomie des étiquettes

Les étiquettes constituent la couche de métadonnées des issues et des PR. Un système d’étiquettes cohérent et bien conçu rend possibles le filtrage, la génération de rapports et l’automatisation. Un système d’étiquettes incohérent (le cas le plus courant, avec des étiquettes ajoutées de manière ad hoc par la personne qui crée l’issue) génère du bruit.

Utilisez un système d’étiquettes nommées. Chaque étiquette possède un préfixe qui identifie sa catégorie :

type: De quel type de travail s’agit-il ?

priority: Quel est le degré d’urgence ?

size: Quelle est la taille de cet élément de travail ?

component: Quelle partie du système ?

composant:kernel · composant:gateway · composant:channels · composant:tools · composant:memory · composant:security · composant:hardware · composant:docs · composant:infra

Utilisez #f1f5f9 (gris clair) pour toutes les étiquettes de composants afin de les distinguer visuellement des autres catégories.

risk: Quel est le niveau de risque ? (reflète AGENTS.md)

status: Où en est-on dans le processus ?

Ce tableau enregistre l’intention de gouvernance et la forme historique de la taxonomie. Pour la sémantique actuelle des labels et le comportement de l’automatisation, utilisez le guide des labels du mainteneur comme référence opérationnelle ; la documentation du mainteneur intègre les corrections ultérieures de la politique de labels issues de #6808.

Les labels actifs de prise en charge communautaire sont good first issue et help wanted sans préfixe ; les lignes de prise en charge status:* ci-dessus relèvent de la taxonomie historique. Les labels de risque opérationnels actuels distinguent également le risque lié à l’issue (rayon d’impact probable du correctif d’après le rapport) du risque lié à la PR (le diff réel en cours de revue). Consultez le guide des labels pour mainteneurs pour connaître la politique en vigueur.

Les étiquettes de clôture terminale relèvent de la politique opérationnelle et ne font pas partie de la taxonomie historique status:* de ce document fondateur. Consultez le guide des étiquettes pour mainteneurs pour connaître les étiquettes de résolution actuelles, et le guide de remplacement pour les règles du processus de remplacement.

rfc: Statut spécifique aux RFC

Retirés dans la rév. 15 et n’ont jamais été créés en tant que libellés actifs. L’état RFC utilise les libellés actifs type:rfc et status:accepted ; voir §8.1.

10. Définition de terminé

« Terminé » a une signification précise. Si vous ne la définissez pas, chacun en aura une définition différente, et les désaccords feront surface au pire moment possible : pendant la revue, pendant la mise en production, ou après qu’un utilisateur a signalé un bogue.

Un élément est Terminé lorsque toutes les conditions suivantes sont remplies :

Pour les modifications de code

• La PR a été examinée et approuvée par le niveau de réviseur requis (selon CODEOWNERS et le niveau de risque).
• Tous les contrôles CI sont validés : cargo fmt, cargo clippy, cargo test
• Des tests existent pour le nouveau comportement ou les modifications apportées (tests unitaires au minimum ; tests d’intégration pour les fonctionnalités visibles par l’utilisateur).
• Aucune couverture de test qui passait avant la PR n’a été perdue.
• La description de la PR explique ce qui a changé et pourquoi (pas seulement « bug corrigé » : quel bug, qu’est-ce qui était incorrect, qu’est-ce qui a été modifié)
• Si le changement affecte le comportement visible par l’utilisateur, la documentation de référence correspondante est mise à jour dans la même PR.
• Si le changement est important : une entrée est ajoutée dans le fichier CHANGELOG.md sous la section de la version concernée.
• Si le changement nécessite un ADR : l’ADR est rédigé, lié et fusionné avant ou avec la PR d’implémentation.

Pour les modifications de documentation

• Le frontmatter YAML est présent et valide.
• Tous les liens internes sont correctement résolus.
• Si le document décrit un comportement actuel : il est conforme à la branche master actuelle.
• Si le document est un ADR : il suit le format de Nygard et possède un champ status.

Pour les versions

• Tous les éléments du jalon sont au statut Terminé ou ont été explicitement déplacés vers le jalon suivant avec un commentaire expliquant la raison.
• L’entrée du CHANGELOG.md pour la version est complète.
• Chaque RFC acceptée dans ce jalon possède une décision durable enregistrée ; les ADR requis et les mises à jour des documents permanents sont fusionnés, et les trackers de livraison restants sont liés
• La version a été testée sur au moins une plateforme (Linux x86_64 au minimum).
• Le tag de version suit la spécification Semantic Versioning.

La règle « Terminé Terminé »

Il existe un concept dans les équipes logicielles concernant le travail qui est « terminé » mais pas « complètement terminé ». « Terminé » signifie que le code a été écrit. « Complètement terminé » signifie qu’il a été testé, documenté, revu, fusionné et publié. La définition de « terminé » ci-dessus décrit ce qui est « complètement terminé ». Rien ne doit être considéré comme terminé tant qu’il ne respecte pas la définition complète.

11. Automatisation

GitHub Projects v2 et GitHub Actions permettent ensemble une automatisation significative qui réduit la charge de coordination manuelle. Voici ce qu’il faut mettre en œuvre, classé par rapport valeur/effort.

11.1 Automatisation du tableau de projet (intégré, aucune action requise)

Configurez ces paramètres dans les paramètres d’automatisation intégrés du projet :

11.2 Workflows GitHub Actions

Étiquetage automatique selon les fichiers modifiés :

Le labelliseur de chemin actif applique des labels de portée aux PR en fonction des fichiers modifiés. Les labels de risque et de taille sont actuellement appliqués par les mainteneurs ; le guide des labels pour mainteneurs est la source de référence pour les noms de labels, le statut d’automatisation et la sémantique du risque.

Demander automatiquement une révision CODEOWNERS (intégré à CODEOWNERS : aucune Action nécessaire) :

GitHub applique automatiquement CODEOWNERS lorsque le fichier existe et que la protection de branche l’exige. Aucune action requise.

Gestion des problèmes obsolètes (exécutée par le mainteneur) :

Aucun workflow GitHub Actions de détection des tickets inactifs n’est actuellement configuré dans le dépôt. Les mainteneurs exécutent des passes de détection d’inactivité pour éviter l’accumulation de tickets inactifs tout en préservant une fenêtre de réponse définie pour la communauté concernée. La politique de tickets inactifs constitue l’unique source opérationnelle pour les délais, les activités qualifiantes, les exclusions et la reprise d’engagement ; le protocole de triage des tickets ne contient que les mécaniques d’exécution.

Étiquetage de la taille des PR (futur/optionnel):

Si une automatisation de la taille est ajoutée ultérieurement, elle doit suivre les noms en direct du guide des labels mainteneurs (size:XS jusqu’à size:XL) et être recalculée lors des mises à jour, afin que le label décrive le diff en cours de révision. D’ici là, les labels de taille sont appliqués par les mainteneurs.

Vérification de l’étape clé lors de la fusion de la PR (.github/workflows/milestone-check.yml) :

Avertir (sans bloquer) si une PR est fusionnée sans issue liée ayant un jalon assigné. Il s’agit d’un rappel léger, pas d’un blocage strict : l’objectif est d’éviter que du travail soit effectué sans être rattaché à une version.

11.3 Ce qu’il ne faut PAS encore automatiser

• Brouillons de version automatisés : Le release-drafter de GitHub est utile, mais il ajoute une surcharge de configuration. Ajoutez-le une fois que l’équipe aura établi un rythme de publication stable.
• Mises à jour automatisées des dépendances (PRs Dependabot) : Activez les mises à jour de sécurité Dependabot (gratuit, faible niveau de bruit), mais reportez les incréments de version automatisés jusqu’à ce que l’équipe dispose d’une stabilité CI. L’incrémentation des versions crée du bruit avant que les fondations CI ne soient solides.
• Automatisation de la planification de sprint : Ne pas automatiser la planification de sprint. Elle nécessite un jugement humain concernant la capacité, la priorité et le contexte de l’équipe, qu’aucune automatisation ne peut remplacer à cette taille d’équipe.

12. Déploiement par phases

La gouvernance et les outils doivent être introduits de manière incrémentale. Tout introduire en même temps crée une surcharge avant que l’équipe ne comprenne pourquoi chaque élément existe.

Phase 1 · Cette semaine : “Fondations”

La configuration de gouvernance minimale viable. Permet à l’équipe de se coordonner immédiatement.

• Créez le projet GitHub avec les champs Statut, Type, Priorité et Jalon.
• Créez les quatre vues de projet (Feuille de route, Tableau, Backlog, Mon travail)
• Activer GitHub Discussions avec des catégories maintenues, documentées dans la communication des contributeurs et la documentation du workflow des mainteneurs
• Créez les trois problèmes RFC pour les propositions existantes (Section 8.4)
• Ajoutez les modèles de problème répertoriés dans la section 7
• Créez le fichier CODEOWNERS (Section 6.1)
• Activer les règles de protection de branche sur master (Section 6.2)
• Ajouter la taxonomie des étiquettes restantes (Section 9) au dépôt
• Épingler les trois problèmes liés aux RFC et le problème de la prochaine version

Signal de succès : Les nouveaux problèmes apparaissent automatiquement dans le projet. L’équipe sait où chercher le travail actif et où publier des idées.

Phase 2 · Jalon v0.7.0 : “The Pipeline”

Établissez le flux de travail complet et remplissez le backlog à partir des RFC acceptées.

• Ajoutez les champs Taille, Niveau de risque et Composant au projet.
• Remplissez le Backlog avec les livrables de la RFC sur l’architecture du micro-noyau.
• Remplissez le Backlog avec les livrables issus de la RFC sur les normes de documentation.
• Effectuer les premiers votes formels de la RFC sur les trois propositions existantes
• Complétez l’ensemble des ADR fondamentaux sélectionnés (ADR-001 à ADR-007 conformément au RFC de documentation)
• Implémentez le workflow Actions de l’étiquetage automatique par chemin
• Mettez en œuvre le workflow de gestion des problèmes obsolètes
• Créez l’équipe GitHub Core Team, fournie sous la forme d’une seule équipe core-contributors plutôt que des deux initialement prévues. L’élément de liste CONTRIBUTORS.md qui l’accompagnait est supprimé ; voir §5.3.

Signal de réussite : L’équipe utilise le tableau quotidiennement. Les éléments progressent à travers les étapes avec des vérifications de passage visibles. Le RFC relatif à l’architecture du micro-noyau comporte un résultat de vote enregistré.

Phase 3 · Jalon v0.8.0 : « Faire grandir la communauté »

À mesure que le système de plugins devient utilisable, des contributeurs externes commenceront à arriver. L’infrastructure de contribution doit être prête.

• Mettre en œuvre le workflow d’étiquetage de la taille des PR
• Créer le premier lot d’éléments good first issue (minimum 5) pour le travail sur le SDK de plugin
• Ajouter l’Good First Issue Index en tant qu’issue épinglée avec des liens vers les good first issues actuels
• Définir le seuil de promotion des idées et promouvoir la première idée de discussion en tant qu’issue
• Documenter le processus d’expansion de la Core Team : critères d’invitation des nouveaux membres de la Core Team

Signal de réussite : Au moins un contributeur externe (ne faisant pas partie de l’équipe actuelle) soumet une PR via un good first issue. La catégorie Ideas des Discussions bénéficie d’une participation active de la communauté.

Phase 4 · v1.0.0 : “Gouvernance durable”

D’ici la v1.0.0, le modèle de gouvernance devrait être autonome : l’équipe ne devrait pas avoir besoin d’y penser, il devrait simplement fonctionner.

• Examinez et mettez à jour le document de gouvernance en fonction de ce qui a fonctionné et de ce qui n’a pas fonctionné.
• Établir la fréquence des versions (à quelle fréquence les versions sont publiées, qui les publie)
• Publiez le document de gouvernance du registre des plugins (conformément à la RFC d’architecture)
• Envisagez l’introduction de cycles à durée limitée (deux ou quatre semaines) si la planification uniquement par jalons semble trop lâche.
• Documentez le processus pour qu’un membre de l’équipe principale puisse se retirer ou devenir inactif.

Signal de succès : Les six derniers mois d’historique de développement montrent une utilisation cohérente du pipeline. Les problèmes sont triés en moins de 3 jours. Les PR sont examinées en moins de 5 jours. Le CHANGELOG est mis à jour à chaque fusion.

Annexe A : Glossaire

Backlog grooming : Activité d’équipe régulière (généralement hebdomadaire ou bimensuelle) au cours de laquelle l’équipe passe en revue le backlog, redéfinit les priorités des éléments, ferme ceux qui sont obsolètes et s’assure que les éléments en tête de liste sont « Defined » et prêts à être pris en charge.

Protection de branche : Une fonctionnalité GitHub qui empêche les pushs directs vers les branches protégées et impose des exigences (revues, vérifications CI) avant la fusion.

CODEOWNERS : Un fichier GitHub qui demande automatiquement des revues aux personnes ou équipes spécifiées lorsque des fichiers qu’elles possèdent sont modifiés dans une PR.

Definition of Done : une liste de contrôle partagée qui précise exactement ce que « terminé » signifie pour un élément de travail. Sans définition partagée, « terminé » signifie quelque chose de différent pour chacun.

Consensus tacite (lazy consensus) : Une approche de prise de décision dans laquelle une action proposée est mise en œuvre à moins que quelqu’un ne s’y oppose dans un délai défini. Réduit la charge liée à l’exigence d’une approbation explicite pour les décisions courantes.

Méritocratie : Un modèle de gouvernance dans lequel l’autorité et l’influence s’acquièrent par des contributions démontrées, et non par l’ancienneté ou le titre. Standard dans les projets open source.

Milestone : Une fonctionnalité de GitHub qui regroupe les issues et les PR par cible de publication. Un milestone représente une version du logiciel.

T-shirt sizing: Une technique d’estimation qui utilise des tailles abstraites (XS, S, M, L, XL) plutôt que des points de récit numériques. Plus facile à utiliser sans données historiques de calibrage et suffisante pour les équipes à un stade précoce.

Triage : Le processus consistant à examiner les nouveaux tickets pour confirmer leur validité, attribuer des étiquettes et une priorité, les lier à des jalons, et déterminer s’ils doivent être ajoutés au backlog ou fermés.

Annexe B : Lectures complémentaires

• Documentation GitHub Projects : référence complète des fonctionnalités de GitHub Projects v2.
• Documentation GitHub Discussions : guide de configuration et options de gouvernance pour GitHub Discussions.
• Référence de syntaxe CODEOWNERS : la syntaxe complète des fichiers CODEOWNERS.
• “Producing Open Source Software” : Karl Fogel : Le livre de référence sur la gestion d’un projet open source. Disponible gratuitement en ligne sur producingoss.com. Les chapitres sur la gouvernance, la gestion des contributeurs et la communication sont directement applicables.
• « Une introduction aux modèles de gouvernance open source » : La documentation sur la gouvernance de l’Apache Software Foundation est un bon modèle de la manière dont un projet open source mature formalise l’autorité et la prise de décision : https://www.apache.org/foundation/governance/
• Linter de prose Vale : Vale : Référencé dans la RFC de documentation ; s’intègre au flux de travail d’amélioration de la documentation good first issue.

Cette proposition a été élaborée dans le contexte de ZeroClaw v0.6.8 et des deux RFC précédentes sur l’architecture et la documentation. Le modèle de gouvernance proposé ici est intentionnellement léger pour un projet dirigé par des étudiants à un stade précoce de croissance communautaire. Il est conçu pour évoluer : en ajoutant des processus au fur et à mesure que l’équipe grandit, et non tout d’un coup.

Le meilleur modèle de gouvernance est le plus simple que l’équipe sera effectivement en mesure de suivre. Commencez par là. Ajustez-le en fonction de ce que vous apprenez.