Modifier une bibliothèque de contrats intelligents sans casser les projets qui l'utilisent

## Concevoir pour les projets qui héritent de la bibliothèque et valider les changements d'abord dans une issue - Ce dépôt est une bibliothèque de contrats intelligents : des contrats abstraits et des bibliothèques réutilisables destinés à être hérités et étendus par des projets tiers, et non une application déployée. La plupart des conventions existent parce que ce code sert de base à d'autres. - Comme les projets héritiers en dépendent, concevez pour l'extension : les fonctions doivent être redéfinissables (override) là où une extension est prévue, les types d'arguments ne doivent pas trop contraindre les héritiers, et l'API publique ne doit pas imposer un contexte d'appel particulier aux contrats enfants. - Lisez d'abord le guide de référence destiné aux contributeurs humains du dépôt ; c'est la source de vérité. Un guide pour assistant IA ne couvre que ce qui est spécifique au travail assisté et les conventions non documentées ailleurs. En cas de désaccord entre les deux, la spécification humaine prévaut. - Discutez de tout changement non trivial dans une issue avant d'ouvrir une pull request. Obtenez d'abord un accord sur l'orientation plutôt que d'implémenter sans y avoir été invité, puis ouvrez la PR dans le périmètre convenu. ## Modifier le fichier qui porte le comportement et ne jamais éditer à la main les fichiers générés - Un dépôt de bibliothèque comporte plusieurs surfaces distinctes : le code source de la bibliothèque (l'API publique), les mocks réservés aux tests qui le reflètent, les définitions d'interfaces pures, les wrappers générés automatiquement, les spécifications de vérification formelle, les sources de documentation et les rapports d'audit historiques. Identifiez quelle surface est propriétaire d'un fichier avant de le modifier, et changez la surface propriétaire du comportement plutôt qu'une surface adjacente. Une même tâche peut toucher plusieurs surfaces à la fois : ne présumez donc pas qu'un changement est « juste du code » ou « juste de la doc » sans vérifier. - Ne modifiez jamais à la main un fichier généré automatiquement ou géré par un outil. Un fichier généré de manière procédurale à partir d'un modèle porte un en-tête l'indiquant : modifiez plutôt le modèle et régénérez, car la CI impose la fraîcheur via une vérification de diff de génération, et les modifications manuelles sont écrasées. Les wrappers générés automatiquement sont généralement exclus de git (gitignore) et reconstruits à la demande. - Laissez les métadonnées gérées par l'outillage à cet outillage. Une ligne d'en-tête « dernière version de mise à jour » par fichier est maintenue automatiquement à partir de l'historique de contrôle de version par l'outillage de publication ; ne l'ajoutez pas et ne la modifiez pas. Votre responsabilité se limite à ce que l'outillage ne gère pas, comme la ligne d'identifiant de licence. ## Laisser au linter les règles de nommage et de visibilité, sans les répéter en revue - Un linter déjà configuré impose les conventions mécaniques sur le code source de la bibliothèque (les mocks et les tests en sont généralement exemptés) : les variables d'état sont privées par défaut, avec `constant` et `immutable` comme seules exceptions ; un préfixe underscore correspond à la visibilité, donc les états et fonctions privés et internes portent un underscore en tête tandis que les membres publics et externes n'en ont pas ; les noms d'interfaces sont préfixés par `I` ; les contrats et événements utilisent le CapWords ; les paramètres et modificateurs utilisent le mixedCase ; les bibliothèques n'exposent que des fonctions internal ou private. - Si une règle de lint détecte déjà un problème, ne dépensez pas de tokens à l'expliquer dans une revue de code ; corrigez-le et passez à la suite. Répéter une règle déjà imposée par le lint dans un commentaire de revue, c'est du bruit, pas du signal. ## Respecter les règles de version du compilateur et d'imports que le linter ne détecte pas - Version plancher du pragma du compilateur : ne choisissez pas la version minimale à la main. Exécutez l'outil de minimisation de pragma du projet, qui parcourt le graphe de dépendances, compile avec chaque version candidate du compilateur, et réécrit la version la plus basse qui fonctionne pour chaque fichier (préfixe `>=` pour les interfaces, `^` pour les implémentations et bibliothèques). Relever ce plancher à la légère peut introduire des opcodes non pris en charge sur certaines chaînes cibles ; la sortie de l'outil est donc la réponse sûre. - Les imports doivent être 100 % nommés, avec accolades, et relatifs dans l'arborescence source. Aucun import générique (wildcard). - L'ordre d'héritage doit être cohérent à l'échelle globale. Si vous modifiez une liste `is A, B, C`, recompilez et exécutez la vérification de l'ordre d'héritage avant de pousser. - Entrées de changelog : tout changement qui modifie le comportement d'un contrat en nécessite une. Ne l'omettez que pour les modifications purement documentaires, les refactorisations internes sans effet visible pour l'utilisateur, ou la plomberie pure du dépôt. ## Ne pas changer les fonctions ni la disposition de stockage existantes, et ajouter peu de dépendances - Les contrats publiés sont hérités en aval et souvent transpilés en une variante upgradable distincte. Ne modifiez pas les signatures des fonctions publiques ou externes existantes, la forme des événements ou erreurs existants, ni la disposition de stockage des contrats existants. Faites des changements additifs ; dépréciez plutôt que de supprimer. Un changement cassant (breaking change) relève d'une décision des mainteneurs liée à une version majeure, jamais d'une chose à introduire pendant un travail courant. - Gardez la surface de dépendances minimale. Réutilisez les utilitaires existants de la bibliothèque avant de vous tourner vers l'extérieur. N'ajoutez pas de package tiers ni de nouvel import externe sans l'accord des mainteneurs ; le code qui a réellement besoin de dépendances tierces plus lourdes a sa place dans un dépôt communautaire ou d'extensions séparé, pas dans la bibliothèque cœur. ## Revérifier à la main le code de cryptographie et de slots de stockage, où l'IA se trompe souvent - Dans ces zones, les suggestions de l'IA sont souvent plausibles mais fausses. Lisez le code environnant et redémontrez l'affirmation avant d'accepter tout changement : - Cryptographie : hachage, ECDSA, séparateurs de domaine des données typées (EIP-712), schémas de signature, et mathématiques de pairing ou BLS. - Dérivations d'emplacements de stockage (storage slots), comme les emplacements namespacés (ERC-7201) : recalculez avec l'utilitaire de dérivation canonique et comparez avec la constante déclarée. La formule dans le commentaire en ligne est obligatoire, pas décorative. - Disposition de stockage pour les contrats traités par un proxy ou un transpileur : ajouter, supprimer ou réordonner des champs casse les proxys déjà déployés. Lisez le diff de disposition de stockage même si la CI l'exécute aussi. - `delegatecall`, l'assembly en ligne et la sécurité mémoire : vérifiez que toute annotation memory-safe est honnête et que l'utilisation de la pile et de l'espace de travail temporaire est bornée. - Blocs `unchecked` : redémontrez l'argument d'impossibilité de dépassement (overflow) pour chaque chemin de code. Le commentaire de justification en ligne est l'engagement que vous devez tenir. - Autorisation de mise à niveau : un hook d'autorisation de mise à niveau est vide dans la base par conception, donc chaque redéfinition (override) doit restreindre qui peut l'appeler. - Constructeurs d'implémentation de proxy : confirmez que les initialiseurs sont désactivés (par exemple, un appel de désactivation des initialiseurs) sur les cibles d'implémentation de proxy UUPS ou transparent. ## Laisser aux humains les changements d'API publique et les avis de sécurité - Ajouter ou renommer l'API publique, ou décider si une fonctionnalité a sa place dans la bibliothèque : ouvrez d'abord une issue et obtenez une décision des mainteneurs. - Évaluations de sécurité et avis d'audit : laissez cela aux auditeurs humains plutôt que d'affirmer qu'un contrat est sûr. - Nouvelles normes d'interface sans orientation explicite. - Restructurer les tests sans changement correspondant du contrat. - Ne fabriquez jamais de récompenses de sécurité. N'affirmez, ne suggérez ni n'inventez de programme de bug bounty, de montant de récompense ou de conditions d'éligibilité. Ne référencez qu'un programme officiellement documenté s'il existe réellement.