Modifier une bibliothèque de données multilangage sans casser ses formats de fichier ni ses API

## Connaître le noyau natif et ses liaisons légères vers les autres langages Considérez le dépôt comme un noyau natif unique, doté de liaisons légères pour les autres langages. Le noyau gère le comportement des formats de données, l'encodage, la compression, les fichiers, les index, les E/S, le stockage d'objets, l'algèbre linéaire, les opérations sur les tables, les domaines facultatifs, l'infrastructure de test et les outils de développement. Les liaisons exposent ce comportement sans dupliquer la validation ni la logique métier. Préservez les caractéristiques principales de l'architecture : E/S asynchrones, mémoire en colonnes native, écritures versionnées avec suivi par manifeste, encodages adaptés aux charges de travail et abstraction de stockage unique pour les magasins d'objets locaux et distants. Lisez le guide du dépôt ainsi que celui de chaque langage ou répertoire concerné avant de planifier des commandes ou des modifications de code. Les règles propres à un répertoire précisent le contrat du dépôt au lieu de le remplacer. ## Garder les formats stables compatibles et changer librement les formats instables Considérez tout format déclaré stable comme un contrat de compatibilité durable. Toute modification de données stables doit préserver à la fois la compatibilité descendante et la compatibilité ascendante. Considérez tout format déclaré instable comme jetable. Il peut évoluer librement ; n'ajoutez ni code de compatibilité, ni migration, ni mécanisme de repli, ni test pour les fichiers créés par des révisions instables antérieures. Évaluez tout nouveau travail de compatibilité par rapport à la dernière version stable publiée, tout en continuant à respecter chaque contrat stable. Les états qui n'existent que sur la branche de développement actuelle ne constituent pas des contraintes de compatibilité. Ne dégradez pas une conception plus propre ou plus complète dans le seul but de préserver un état intermédiaire non publié. ## Utiliser les commandes et profils de compilation documentés, sans changer de chaîne d'outils Avant de les exécuter, repérez les commandes documentées de vérification, de test, d'analyse statique, de formatage, de couverture, de mesure des performances et d'intégration pour le langage concerné. Utilisez les sélecteurs de paquets et de tests fournis par le dépôt au lieu d'inventer un flux de travail parallèle. Ne remplacez pas le gestionnaire d'environnement ou la chaîne d'outils parce qu'une commande semble absente, lente ou indisponible. Si une commande propre à un langage échoue en dehors du flux de travail documenté, corrigez d'abord l'utilisation de l'environnement, puis relancez la commande prescrite. Ce n'est qu'ensuite que vous pourrez conclure à l'indisponibilité d'une dépendance ou d'un outil. Utilisez les profils de compilation définis par le dépôt plutôt que des réglages d'optimisation improvisés. Mesurez les performances et effectuez le profilage avec une version optimisée qui conserve les symboles de débogage. Désactivez l'optimisation à l'édition des liens uniquement pour le débogage local, les mesures limitées par les E/S ou les analyses du temps de compilation lorsqu'elle ne peut pas influer sur le goulot d'étranglement mesuré. Pour les tests d'intégration, démarrez uniquement les services de test requis, définissez les valeurs d'environnement documentées et exécutez la cible d'intégration désignée. ## Écrire un code ciblé qui traite les données en flux sans les accumuler en mémoire Utilisez l'anglais dans le code, les exemples et les commentaires. Le code doit être optimisé pour la lisibilité autant que pour l'exécution. N'ajoutez un commentaire que s'il explique une raison non évidente et, avant la revue, remplacez les affichages directs de débogage par le système établi de traçage ou de journalisation. Extrayez dans un utilitaire partagé toute logique répétée à deux endroits ou plus. Conservez la logique utilisée une seule fois à son point d'appel. N'introduisez un utilitaire que s'il réduit sensiblement la charge cognitive ou élimine une duplication importante ; n'ajoutez pas une fine couche qui se contente de renommer ou de transmettre un appel. Gardez les modifications ciblées. Évitez les remaniements opportunistes, les reformatages et les retouches esthétiques. Préservez le traitement en flux au lieu d'accumuler les lots en mémoire et, pour représenter l'appartenance à un ensemble dense d'entiers, préférez des structures de bitmap compactes aux ensembles de hachage génériques. ## Garder les liaisons légères et déprécier les anciennes API au lieu de les casser Centralisez la validation et la logique dans le noyau natif, et conservez chaque liaison de langage sous la forme d'une fine couche. Employez les mêmes noms de paramètres dans toutes les liaisons ; renommez-les partout ou nulle part. Ne cassez jamais directement une signature publique existante. Marquez l'ancienne méthode comme obsolète avec l'annotation prise en charge par le langage, puis ajoutez une nouvelle méthode. Remplacez les groupes d'indicateurs booléens mutuellement exclusifs par un unique paramètre d'énumération ou de mode. Lorsque le comportement du noyau change, mettez à jour simultanément chaque liaison concernée, chaque interface générée, chaque exemple et chaque test de compatibilité. Une liaison ne doit pas réinterpréter silencieusement une valeur rejetée par le noyau. ## Nommer les valeurs selon ce qu'elles sont et rejeter les entrées non valides avec des erreurs claires Nommez une variable selon ce que représente sa valeur, et non selon l'usage qui en est fait. Supprimez les préfixes redondants lorsque le type ou le module conteneur indique déjà le domaine. Utilisez systématiquement une seule forme plurielle approuvée dans les API et la documentation, et préférez les noms indépendants du stockage aux termes propres à un fournisseur. Lorsque vous renommez un type, une structure ou une énumération, mettez à jour simultanément les méthodes, les champs, les variables, les tests et la documentation. Validez les entrées aux frontières de l'API et rejetez les valeurs non valides avec des erreurs explicites. Ne les bornez ni ne les ajustez jamais silencieusement. Rejetez les options de construction ou de configuration mutuellement exclusives lorsqu'elles sont toutes deux présentes. Mentionnez dans les messages d'erreur les noms, valeurs, tailles et types des variables concernées. ## Ajouter peu de dépendances et garder les fichiers de verrouillage synchronisés Avant d'ajouter un paquet externe, privilégiez la bibliothèque standard ou les dépendances déjà présentes dans l'espace de travail. Veillez à ce que les modifications des fichiers de verrouillage soient intentionnelles, annulez les mises à niveau sans rapport et ne figez une dépendance défectueuse qu'avec un commentaire contenant un lien vers le ticket correspondant dans le projet d'origine. Lorsqu'une dépendance de l'espace de travail change, actualisez le fichier de verrouillage racine et celui de chaque liaison exclue au moyen des contrôles documentés propres à chaque manifeste, puis validez toutes les mises à jour correspondantes. Maintenez actif le dispositif de synchronisation hors ligne des fichiers de verrouillage. Placez les dépendances facultatives ou propres à un domaine derrière des indicateurs de fonctionnalité. Préférez un paquet distinct pour toute fonctionnalité importante propre à un domaine, afin que les compilations par défaut et leurs utilisateurs n'embarquent pas de code inutile. ## Ajouter un test à chaque correction de bug et à chaque nouvelle fonctionnalité Toute correction de défaut et toute fonctionnalité nécessite des tests correspondants. N'acceptez pas de code sans tests. Utilisez le mécanisme de tests paramétrés du langage lorsque les cas ne diffèrent que par leurs entrées, et donnez-leur des noms lisibles. Remplacez les affichages dans les tests par des assertions, car une sortie seule ne permet pas de détecter les régressions. Étendez un test existant s'il couvre déjà le comportement, au lieu d'ajouter un fichier de test redondant. Placez les ajouts à l'emplacement de test établi. Tout test ignoré doit contenir un lien vers un ticket de suivi ; n'ajoutez jamais une annotation d'omission isolée sans justification durable. ## Tester avec des données nulles ou vides et d'anciens fichiers stables Incluez des scénarios à fragments multiples pour les lectures, les index et les analyses. Dans les tests d'index, couvrez les éléments nuls, les collections entièrement nulles, les collections vides et les colonnes nulles. Les tests d'index vectoriels doivent vérifier une métrique de rappel d'au moins 0,5 au lieu de simplement confirmer que la création de l'index a réussi. Pour la compatibilité descendante, utilisez des jeux de données intégrés au dépôt et produits par d'anciennes versions stables. Conservez un script de génération de données qui vérifie la version du producteur, et copiez ces données de test vers un stockage temporaire avant de les lire. Ne désactivez pas les tests de documentation dans le seul but d'éviter la compilation. Rédigez des exemples qui se compilent dans un contexte structuré comme une fonction. Excluez de la couverture les utilitaires réservés aux tests au moyen de l'annotation de couverture approuvée par le projet, au lieu d'abaisser les seuils de couverture du code de production. ## Documenter chaque API publique avec un exemple qui compile Documentez chaque API publique et fournissez un exemple. Créez des liens vers les types et méthodes concernés et, lors de toute refactorisation du code, maintenez les exemples synchronisés avec les signatures réelles. Utilisez des arborescences ASCII pour les structures hiérarchiques telles que les couches d'encodage, les formats de fichiers et les organisations du stockage. Respectez le contrat d'indentation du système de documentation, notamment les quatre espaces d'indentation sous les directives d'admonition. Relisez les commentaires et la documentation avant la revue. Une documentation qui ne se compile plus ou qui mentionne une API obsolète constitue un défaut de compatibilité, et non un problème esthétique. ## Étiqueter les tickets et passer le lint avant d'ouvrir une demande de modification Lorsque vous créez un ticket au moyen d'un outil en ligne de commande ou d'une API, transmettez explicitement l'étiquette correspondant à un défaut, une fonctionnalité ou un travail de performance, car l'automatisation du gabarit peut être contournée. Préfixez le titre avec la classification correspondante afin que l'automatisation fondée sur le contenu dispose d'un signal de repli fiable. Utilisez les préfixes de titre de modification conventionnels du dépôt et ajoutez une portée lorsqu'elle est utile. Avant de créer ou d'actualiser une demande de modification, exécutez les contrôles d'analyse statique requis pour chaque interface de langage concernée, même s'ils sont coûteux. Pour les commandes d'analyse statique, suivez le flux de travail d'environnement décrit dans le guide de chaque langage. Si un contrôle obligatoire ne peut pas être exécuté, indiquez explicitement le blocage dans le résumé de la demande de modification au lieu de laisser entendre que la validation est terminée. ## Concentrer les revues sur les bugs graves et les problèmes de sécurité L'attention des contributeurs et des responsables de maintenance est limitée. Gardez les revues concises et claires, et concentrez-vous sur les défauts les plus graves, les régressions de performances et les problèmes de sécurité. Ne répétez pas le détail des modifications ni ce qui est déjà correct. Vérifiez la cohérence des noms, les pratiques établies de gestion des erreurs et la couverture des tests. Citez l'emplacement concerné et expliquez la conséquence concrète de chaque constat bloquant.