Vous avez créé un asset réutilisable.
Il est :
- paramétrable ;
- documenté ;
- accompagné d’une
eval suite; - suffisamment propre pour être réutilisé par une autre équipe.
Une nouvelle question apparaît alors :
Comment transformer cet asset privé en contribution qu’un maintainer externe peut réellement accepter ?
Partager du code ne consiste pas simplement à publier ce qui fonctionne.
Il faut préparer la contribution de manière à ce qu’une personne qui n’a jamais travaillé avec vous puisse :
- comprendre ce que fait le code ;
- exécuter un exemple ;
- vérifier le comportement ;
- identifier les hypothèses ;
- confirmer que le code peut légalement être partagé.
Autrement dit :
PRIVATE ASSET
↓
PACKAGE
↓
CONTRIBUTION READINESS
↓
MAINTAINER REVIEW
↓
SHARED INFRASTRUCTURE
Le passage du code privé à l’infrastructure partagée repose donc sur une idée centrale :
A maintainer accepts what they can verify.
Un asset réutilisable est déjà proche d’une contribution
Lorsque vous avez correctement préparé un accelerator pour votre propre équipe, vous avez déjà effectué une grande partie du travail.
Vous avez normalement :
- extrait les valeurs spécifiques au client ;
- documenté les assumptions ;
- préparé les tests ou
evals; - rendu l’installation ou la configuration compréhensible.
Ces éléments sont précisément ceux dont un maintainer a besoin.
Pourquoi ?
Parce qu’un maintainer ne connaît pas votre contexte initial.
Il ne sait pas :
- pourquoi certaines décisions ont été prises ;
- quelles dépendances sont nécessaires ;
- ce qui est spécifique au client ;
- ce qui constitue réellement un comportement correct.
La contribution doit donc transporter avec elle suffisamment de contexte pour être vérifiable sans reconstruction.
La contribution n’est pas seulement du code
Une erreur fréquente consiste à penser qu’une contribution correspond uniquement à :
git commit
↓
pull request
En réalité, un maintainer doit répondre à plusieurs questions :
What does it do?
Can I run it?
Can I test it?
What does it assume?
Can we legally accept it?
Si la contribution ne répond pas à ces questions, elle peut rester ouverte longtemps, même lorsque le code est techniquement correct.
Choisir le bon contribution channel
Tous les types de contribution ne doivent pas être envoyés au même endroit.
Le module distingue notamment plusieurs situations.
Focused reference implementation
Un exemple focalisé montrant un pattern Claude de manière claire et complète peut correspondre à un repository tel que le Claude Cookbook.
Le point important est le mot :
focused
Le maintainer doit pouvoir comprendre le pattern sans devoir analyser une application entière.
Ce qui correspond à un Cookbook
Un exemple peut montrer :
- un pattern de prompting ;
- une utilisation précise d’un tool ;
- une intégration focalisée ;
- un workflow démontrant une technique clairement identifiable.
L’objectif est de montrer une idée de manière lisible et reproductible.
Par exemple :
Focused pattern
↓
Runnable example
↓
Test
↓
Documentation
Ce qui ne correspond pas nécessairement à un Cookbook
Imaginez une application complète comprenant :
- frontend ;
- backend ;
- base de données ;
- système d’authentification ;
- scripts de déploiement ;
- plusieurs agents ;
- plusieurs intégrations MCP.
Même si l’application fonctionne parfaitement, elle peut être trop large pour un canal conçu pour recevoir des exemples ciblés.
Le problème n’est pas la qualité.
Le problème est le shape mismatch.
Le canal de contribution est conçu pour examiner une certaine forme de contribution.
Extraire le pattern réutilisable
Face à une application trop large, la bonne approche consiste souvent à identifier le pattern réellement partageable.
Par exemple :
FULL CUSTOMER APPLICATION
↓
Identify reusable pattern
↓
Remove customer specifics
↓
Create focused example
↓
Contribute
La contribution ne reprend donc pas nécessairement toute l’application.
Elle reprend la partie qui possède une valeur générique.
Les tools et MCP servers suivent leur propre repository
Lorsqu’il s’agit :
- d’un tool existant ;
- d’un
MCP server; - d’un fix pour un projet existant ;
la contribution doit généralement suivre les conventions du repository concerné.
Chaque repository peut avoir :
- ses conventions ;
- ses tests ;
- son format de pull request ;
- ses règles de contribution ;
- ses exigences de documentation.
Le réflexe n’est donc pas :
« Je vais mettre cela dans le Cookbook. »
Mais :
« Quel canal est conçu pour recevoir cette contribution précise ? »
Le principe à retenir
CONTRIBUTION
↓
Identify its shape
↓
Choose matching channel
Il faut faire correspondre :
WHAT YOU BUILT
avec :
WHAT THE REPOSITORY IS DESIGNED TO REVIEW
Le maintainer doit pouvoir vérifier la contribution
Le module identifie quatre éléments essentiels.
1. Le code doit faire une chose claire
Une contribution très large force le reviewer à reconstruire votre intention.
Un code focalisé répond immédiatement à une question :
Que cherche à démontrer ou corriger cette contribution ?
Par exemple :
GOOD
"Adds retry handling for tool execution"
est beaucoup plus simple à examiner que :
"Adds complete production agent framework"
contenant plusieurs dizaines de décisions indépendantes.
Pourquoi le focus accélère la review
Un maintainer examine généralement beaucoup de contributions.
Chaque élément supplémentaire augmente :
- la surface de code ;
- le nombre de comportements à comprendre ;
- le nombre de régressions possibles ;
- le temps nécessaire à la validation.
Un PR focalisé réduit cette charge.
Conceptuellement :
SMALL FOCUSED PR
↓
Clear intent
↓
Easy verification
↓
Faster review
2. Un exemple doit montrer le comportement
Le maintainer ne devrait pas devoir construire lui-même un harness complet pour comprendre comment la contribution fonctionne.
Un exemple exécutable permet de passer de :
"I think this works"
à :
"Here is how to run it"
L’exemple répond notamment à :
- comment initialiser le composant ;
- quels inputs fournir ;
- quel output attendre ;
- dans quel contexte il est censé fonctionner.
Exemple conceptuel
Supposons que vous contribuez un wrapper autour d’une API.
Le code seul pourrait être :
def call_service(payload):
...
Une contribution plus vérifiable fournit également quelque chose comme :
result = call_service(
{"query": "example"}
)
print(result)
Le maintainer peut immédiatement voir l’usage attendu.
3. Un test doit prouver le comportement
L’exemple montre comment utiliser la contribution.
Le test démontre automatiquement qu’elle produit bien le comportement attendu.
Cette distinction est importante.
EXAMPLE
"Here is how it works."
TEST
"Here is proof that it still works."
Le maintainer n’a plus besoin de reconstruire votre raisonnement.
Il exécute le test.
Le test réduit le coût de confiance
Sans test, le reviewer doit :
- lire le code ;
- comprendre l’intention ;
- imaginer les cas attendus ;
- exécuter manuellement ;
- déterminer lui-même si le résultat est correct.
Avec un test :
Contribution
↓
Run test
↓
Expected behavior verified
Cela ne remplace évidemment pas la review du code, mais réduit fortement la quantité de travail nécessaire pour confirmer son comportement.
4. Les assumptions doivent être explicites
Un asset peut fonctionner parfaitement dans votre environnement tout en échouant ailleurs.
Cela peut dépendre de :
- versions ;
- services disponibles ;
- variables d’environnement ;
- permissions ;
- structure des données ;
- infrastructure ;
- configuration particulière.
Le maintainer doit connaître ces assumptions.
Par exemple :
Requires:
- Python version X
- specific environment variable
- network access to service Y
- read-only permission to repository
Sans ces informations, une erreur environnementale peut être interprétée comme un bug de la contribution.
Les quatre éléments de vérifiabilité
On peut donc résumer :
CONTRIBUTION
│
├── Focused code
├── Runnable example
├── Test
└── Assumptions
Ces quatre éléments permettent au maintainer de comprendre et vérifier le comportement.
Mais il existe une gate avant la technical review
Même une contribution parfaite techniquement peut être impossible à accepter.
Pourquoi ?
Parce que vous ne possédez pas nécessairement le droit de la partager.
C’est particulièrement important lorsqu’un code vient d’un engagement client.
Rights and attribution come first
Le module insiste sur un ordre précis :
RIGHTS / LICENSING
↓
TECHNICAL REVIEW
Ce n’est pas une formalité secondaire.
C’est une gate.
Avant de proposer une contribution, il faut vérifier que vous avez effectivement le droit de partager le code.
Pourquoi un engagement client pose un problème particulier
Supposons qu’une équipe développe pendant une mission :
- un tool ;
- un agent ;
- un pattern ;
- un fix.
Techniquement, le développeur peut avoir écrit lui-même le code.
Cela ne signifie pas automatiquement que ce code peut être publié.
Il peut exister :
- des obligations contractuelles ;
- des restrictions de propriété intellectuelle ;
- des clauses de confidentialité ;
- des dépendances à du code tiers ;
- des obligations d’attribution.
Le fait d’être l’auteur technique ne garantit donc pas à lui seul le droit de contribution.
Attribution
Lorsqu’une contribution utilise ou adapte du travail antérieur, ce travail doit également être correctement attribué lorsque les conditions applicables l’exigent.
Le maintainer ne doit pas découvrir après coup qu’une partie du code vient d’une source qui impose des obligations particulières.
Ce qui se passe si les droits ne sont pas clairs
La bonne réponse n’est pas :
Publier d’abord et résoudre le problème ensuite.
Le module recommande :
Do not contribute it: escalate to the owner instead.
Autrement dit :
Rights unclear
↓
STOP
↓
Escalate
La contribution technique attend que la question des droits soit résolue.
Étude de cas : le PR correct que personne ne pouvait vérifier
Le module présente un échange particulièrement révélateur.
Un développeur se plaint qu’un pull request est ouvert depuis plusieurs semaines sans review.
Son raisonnement est simple :
Le code fonctionne. Je l’utilise tous les jours.
Le maintainer répond en substance :
Il fonctionne probablement pour vous. Mais je ne peux pas le vérifier.
Le PR ne contient :
- aucun test ;
- aucun exemple ;
- aucune explication des assumptions.
Le reviewer doit donc reconstruire lui-même tout ce que le développeur sait déjà.
Pourquoi le PR reste en attente
Ce n’est pas nécessairement parce que le maintainer pense que le code est mauvais.
C’est une question de coût de review.
Le reviewer doit transformer :
UNKNOWN CONTRIBUTION
en :
UNDERSTOOD
+
RUNNABLE
+
VERIFIED
Si cette transformation lui demande plusieurs heures, le PR passe derrière des contributions plus faciles à vérifier.
Le contexte invisible de l’auteur
Le problème vient souvent de quelque chose de très humain.
L’auteur connaît tellement bien son code que certaines informations lui paraissent évidentes.
Il sait :
- comment l’exécuter ;
- ce qu’il doit produire ;
- quelles dépendances sont nécessaires ;
- quels cas sont normaux ;
- quelles erreurs sont attendues.
Il oublie que le maintainer ne possède aucune de ces informations.
Le reviewer ne doit rien avoir à reverse-engineer
La contribution idéale laisse très peu de choses implicites.
CODE
→ clear purpose
EXAMPLE
→ clear execution
TEST
→ clear verification
ASSUMPTIONS
→ clear environment
Le maintainer peut se concentrer sur la qualité de la contribution plutôt que sur la reconstruction du contexte.
Trois cas typiques
Le module propose trois situations permettant de comprendre le choix du channel et la readiness.
Cas A : un tool focalisé qui encapsule une API
Vous disposez d’un tool propre qui encapsule une API dans une fonction claire.
La contribution ne contient que la fonction.
Le channel naturel est généralement :
le repository propre au tool.
Mais il manque quelque chose pour que la contribution soit facilement vérifiable.
Le module attend ici :
un test prouvant le comportement du wrapper.
Le problème n’est pas le focus.
Le code est déjà focalisé.
Le problème est la vérification.
Cas B : une application complète de customer service
Le développeur souhaite partager toute l’application :
- UI ;
- logique métier ;
- déploiement ;
- plusieurs composants.
Le problème principal est la taille et la forme.
Un canal destiné aux exemples focalisés n’est pas conçu pour examiner une application entière.
La bonne stratégie consiste à :
extraire le reusable pattern et le transformer en exemple focalisé.
La contribution peut alors correspondre à un canal comme le Cookbook.
Cas C : un fix d’une ligne dans un exemple existant
Le fix appartient à un exemple déjà présent.
Le channel logique est :
le repository dans lequel cet exemple existe.
Mais le correctif provient d’un engagement client.
La première question n’est donc pas technique.
Il faut vérifier :
les rights to contribute.
La gate licensing intervient avant la review.
Tableau de décision
| Situation | Channel | Missing readiness item |
|---|---|---|
| Tool focalisé | Repository du tool | Test |
| Application complète | Extraire le pattern puis contribution focalisée | Réduction du scope |
| Fix dans un exemple existant | Repository concerné | Rights/licensing check |
Contribution readiness : checklist
Avant d’ouvrir un pull request, vérifiez les points suivants.
Scope
La contribution fait-elle une chose clairement identifiable ?
Example
Existe-t-il un exemple exécutable montrant le comportement ?
Test
Existe-t-il un test démontrant le résultat ?
Assumptions
Les contraintes environnementales sont-elles documentées ?
Rights
Avez-vous confirmé le droit de partager ce code ?
Attribution
Les éléments provenant de travaux antérieurs sont-ils correctement attribués lorsque nécessaire ?
Exemple de structure d’une contribution propre
my-contribution/
│
├── implementation.py
├── example.py
├── test_implementation.py
└── README.md
Le README peut expliquer :
Purpose
Requirements
Assumptions
Installation
Example
Known limitations
Le maintainer dispose ainsi d’un package cohérent.
Pourquoi l’exemple et le test sont différents
Cette distinction peut constituer un piège d’examen.
Considérons :
result = wrapper.call("hello")
print(result)
C’est un example.
Il montre comment utiliser la fonction.
Un test ressemble plutôt conceptuellement à :
result = wrapper.call("hello")
assert result.status == "success"
Le test définit un comportement vérifiable.
Les deux sont utiles.
Ne pas demander au reviewer de deviner les assumptions
Un autre piège consiste à fournir un test qui fonctionne uniquement dans votre environnement, sans expliquer pourquoi.
Par exemple :
test passes locally
test fails for maintainer
La cause réelle peut être une assumption non documentée :
- service disponible uniquement sur un réseau interne ;
- variable d’environnement absente ;
- permission particulière ;
- fichier de configuration non fourni.
L’assumption fait donc partie de la contribution.
Contribution et réutilisabilité
Il existe une continuité logique entre l’article précédent et celui-ci.
Un accelerator interne demande :
PARAMETERIZATION
+
DOCUMENTATION
+
EVAL
Une contribution externe ajoute notamment :
FOCUSED SCOPE
+
RUNNABLE EXAMPLE
+
TEST
+
RIGHTS CHECK
On peut donc représenter la progression ainsi :
WORKING BUILD
↓
REUSABLE ASSET
↓
VERIFIABLE CONTRIBUTION
↓
SHARED INFRASTRUCTURE
Quand ne pas contribuer ?
Il existe également des situations où la bonne décision est de ne pas publier.
Par exemple :
- droits non clarifiés ;
- licensing incompatible ;
- contenu fortement lié au client ;
- secrets ou données privées ;
- scope impossible à nettoyer correctement.
Dans ce cas, la bonne action n’est pas de contourner le problème.
Le module recommande l’escalade vers le propriétaire concerné.
Principe → Exemple → Erreur fréquente → Bonne pratique
Principe
Un maintainer doit pouvoir vérifier une contribution sans reconstruire votre contexte.
Exemple
Un tool est proposé avec :
implementation
+ example
+ test
+ assumptions
Erreur fréquente
Soumettre uniquement le code en expliquant :
« Il fonctionne chez moi. »
Bonne pratique
Réduire la contribution à un scope clair, fournir un exemple exécutable et un test, documenter les assumptions et vérifier les droits avant la review technique.
Ce qu’il faut retenir pour l’examen
Face à un scénario, recherchez les signaux suivants.
| Signal dans la question | Réponse probable |
|---|---|
| PR impossible à vérifier | Ajouter test + example |
| Maintainer doit reconstruire le contexte | Documenter assumptions |
| Application entière envoyée dans un repo d’exemples | Réduire à un focused pattern |
| Tool existant | Utiliser son propre repository |
| Fix d’un exemple existant | Contribuer dans le repository concerné |
| Code provenant d’un client | Vérifier rights/licensing |
| Droits impossibles à confirmer | Escalate, ne pas contribuer |
| Code techniquement correct mais review bloquée | Problème de verifiability, pas forcément de code |
Piège d’examen : « le code fonctionne, donc il est prêt à être contribué »
Faux.
Le raisonnement correct est :
CODE WORKS
↓
Can a maintainer understand it?
↓
Can they run it?
↓
Can they test it?
↓
Are assumptions documented?
↓
Do we have the rights?
↓
CONTRIBUTION READY
La qualité fonctionnelle n’est donc qu’une partie de la readiness.
Piège d’examen : choisir le mauvais channel
Une autre erreur fréquente consiste à sélectionner le repository en fonction de sa visibilité ou de sa popularité plutôt qu’en fonction de la contribution.
Le choix correct suit la forme de l’asset :
Contribution shape
↓
Matching channel
Pas :
Most famous repository
↓
Send everything there
Piège d’examen : technical review avant licensing
Dans un contexte client, cette réponse est généralement mauvaise :
« Soumettez le PR, puis vérifiez la licence si le maintainer l’accepte. »
La gate arrive avant.
RIGHTS
↓
TECHNICAL READINESS
↓
REVIEW
Fiche rapide
| Concept | À retenir | Exemple | Piège |
|---|---|---|---|
| Contribution channel | Adapter le channel au type d’asset | Tool → repo du tool | Tout envoyer au Cookbook |
| Focused contribution | Un objectif clair | Un seul pattern | PR trop large |
| Runnable example | Montrer l’utilisation | example.py | Description sans exécution |
| Test | Prouver le comportement | Assertion automatisée | « Works for me » |
| Assumptions | Documenter l’environnement | Permissions, dependencies | Laisser le reviewer deviner |
| Rights | Vérifier le droit de publier | Code client | Review technique d’abord |
| Attribution | Reconnaître les travaux antérieurs | Source/licence appropriée | Ignorer le code repris |
| Maintainer verification | Minimiser le reverse engineering | Code + example + test | Compter sur le contexte oral |
À retenir en une phrase
Une contribution est prête lorsqu’elle est placée dans le bon channel, suffisamment focalisée pour être comprise rapidement, accompagnée d’un exemple et d’un test permettant de la vérifier, documentée pour exposer ses assumptions et juridiquement partageable.
Le passage du code privé à l’infrastructure partagée ne consiste donc pas seulement à rendre le repository public.
Il consiste à transformer :
"Trust me, it works."
en :
"Here is the code.
Here is how to run it.
Here is the test.
Here are the assumptions.
Here is why we can contribute it."
C’est cette capacité à être vérifiée par une personne extérieure au projet qui transforme un asset interne en contribution réellement maintenable.
