Modifiez un espace de travail Rust de bibliothèques et de CLI en le comparant à l’outil de référence

## Placez les changements dans le crate responsable et gardez les API bas niveau légères Considérez le dépôt comme un espace de travail composé de plusieurs crates et destiné à la fois aux utilisateurs de bibliothèques et d’outils en ligne de commande. Lisez les manifestes de l’espace de travail avant toute modification pour connaître la version minimale de Rust prise en charge, le graphe des fonctionnalités, les responsabilités des crates et les points d’entrée publics. Séparez les API d’infrastructure de bas niveau des API d’interface de haut niveau : - les API de bas niveau doivent privilégier les références, exposer explicitement l’état de travail mutable et éviter les clones de commodité ; - les API de haut niveau peuvent accepter certaines allocations ou prises de possession pour faciliter leur utilisation ; - les objets légers propres aux plateformes doivent généralement emprunter le dépôt ; - les caches coûteux peuvent posséder ou cloner l’état du dépôt lorsque les durées de vie domineraient autrement l’API. Utilisez `Options` pour les comportements à embranchements qui peuvent avoir des valeurs par défaut. Utilisez `Context` pour les données nécessaires à l’opération et auxquelles il n’est donc pas sûr d’attribuer une valeur par défaut. Placez les modifications dans la crate qui possède la structure de données ou l’opération concernée. Conservez le comportement partagé de la ligne de commande dans une couche CLI commune au lieu de le dupliquer dans plusieurs binaires. Avant de modifier une surface publique, prenez en compte à la fois les appels directs à la bibliothèque et le comportement de la ligne de commande. ## Commencez par un test qui échoue et comparez à l’outil de référence Commencez toute modification de comportement par un test de régression qui échoue pour la raison prévue. Concentrez le test sur le comportement observable ; laissez le compilateur Rust détecter les erreurs ordinaires de type et de possession. Lors de l’implémentation d’un protocole ou d’un format de fichier établi, utilisez si possible l’implémentation de référence dominante comme oracle. Exécutez des cas équivalents sur les deux implémentations et examinez toute différence sémantique au lieu de supposer leur compatibilité. Exécutez les tests existants avant toute modification afin que les échecs préexistants ne soient pas attribués au changement. Utilisez : - des tests unitaires pour les algorithmes locaux et les transformations de données ; - des tests d’intégration pour les frontières entre crates ; - des tests de parcours pour le comportement de bout en bout de la ligne de commande ; - des dépôts réels ou des jeux de données réalistes pour les chemins sensibles à la compatibilité. Chaque message d’assertion doit expliquer l’invariant contrôlé, et non simplement indiquer qu’une assertion a échoué. Ajoutez une documentation claire des fixtures qui décrit le comportement testé et précise quels détails sont essentiels. Préférez les chaînes de documentation lorsque le système de fixtures les prend en charge. ## Remplacez unwrap() par des erreurs qui disent ce qui a échoué et où N’utilisez jamais `unwrap()` dans le code de production. Évitez-le également dans les tests ; préférez `?`, ou n’utilisez `expect()` qu’avec une explication concise de la raison pour laquelle la condition doit être satisfaite. Préservez les chaînes d’erreurs complètes afin que les utilisateurs comprennent ce qui a échoué et à quel endroit. Les binaires en ligne de commande peuvent utiliser un type d’erreur flexible de premier niveau, mais les crates de niveau inférieur doivent respecter la convention structurée de l’espace de travail. Avant d’ajouter une erreur, examinez le manifeste de la crate et le code voisin : - si la crate utilise déjà le nouveau framework d’erreurs transportant du contexte, poursuivez selon ce modèle ; - si elle utilise encore une ancienne énumération d’erreurs dérivée, restez cohérent dans cette crate, sauf si la migration fait explicitement partie du périmètre. Dans le modèle transportant du contexte : - créez des messages statiques ou formatés au moyen de l’utilitaire du projet ; - ajoutez du contexte lors de la propagation de l’erreur d’un appelé ; - levez un message autonome lorsqu’il n’existe aucune erreur d’un appelé ; - effacez le type des erreurs uniquement lorsqu’une frontière de fonction de rappel l’exige ; - convertissez l’enveloppe d’exception du projet en erreur standard uniquement aux frontières d’interopérabilité. Si l’enveloppe d’exception du projet n’implémente délibérément pas le trait d’erreur standard, ne la forcez pas dans des API d’erreur génériques. Convertissez-la avec la méthode de frontière fournie. Les tests qui renvoient une erreur standard mise en boîte doivent transformer l’enveloppe avant d’utiliser `?`. Utilisez les traits d’extension et les imports d’erreur établis au lieu de reconstruire manuellement les chaînes d’erreurs. ## Évitez les clones inutiles et traitez les chemins du dépôt comme des octets Privilégiez les références dans les crates de bas niveau afin d’éviter les clones coûteux. Ne détachez pas un handle adossé au dépôt, sauf si une valeur possédée est explicitement requise et que l’API ne peut pas accepter la forme attachée. Utilisez l’abstraction de concurrence de l’espace de travail pour la mutabilité intérieure. Ne lui substituez pas de primitives de synchronisation sans rapport sans avoir vérifié la compatibilité des fonctionnalités et le comportement sur les plateformes. Traitez les chemins du système de gestion de versions comme des données orientées octets, y compris sur les plateformes dont les API de chemins natives utilisent d’autres encodages. Ne convertissez les chemins du dépôt en chemins du système d’exploitation qu’au moyen des utilitaires de chemin du projet ou d’un type de frontière dédié. Ne supposez pas qu’un chemin de dépôt valide est un texte Unicode valide. Évitez toute conversion avec perte lors de l’analyse, de la comparaison, du stockage et du traitement des protocoles. Mesurez les chemins critiques avant d’ajouter une prise de possession, une mise en cache ou une allocation. La commodité appartient à la couche de haut niveau ; les primitives de bas niveau doivent préserver la maîtrise et un coût prévisible. ## Testez toutes les combinaisons de fonctionnalités, pas seulement le build par défaut Utilisez l’exécuteur de tâches du dépôt pour la commande de test complète, les contrôles de configuration de l’espace de travail, le lint, les tests de parcours et les builds de documentation. N’utilisez directement `cargo test` que lorsqu’une exécution limitée aux tests unitaires est intentionnellement suffisante. Vérifiez les variantes de publication prises en charge, notamment le build par défaut et les ensembles de dépendances allégés ou minimaux. Une modification est incomplète si elle ne fonctionne qu’avec les fonctionnalités par défaut. Exercez les combinaisons de fonctionnalités documentées de l’espace de travail, notamment les variantes petites, allégées, maximales et pures lorsqu’elles existent. Vérifiez que les dépendances facultatives et les abstractions de plateforme se compilent dans chaque combinaison concernée. Sur les plateformes où le contenu des fixtures générées varie, utilisez le mécanisme de stabilisation des archives du dépôt. Préférez les archives de fixtures fournies à une génération locale propre à la plateforme lorsque la stabilité octet par octet est importante. Si le dépôt définit un indicateur d’environnement propre à la plateforme pour les tests d’archives sous macOS ou Windows, appliquez-le exactement comme indiqué dans la documentation. N’ignorez pas silencieusement les tests concernés sur les autres plateformes. Exécutez des tests de commandes de bout en bout pour les modifications de CLI visibles par les utilisateurs et comparez-les à l’implémentation de référence lorsque cela est possible. ## Écrivez des commits utiles au changelog et marquez les changements incompatibles Utilisez des commits conventionnels ayant un objectif précis : - ajoutez un préfixe conventionnel uniquement lorsque la modification doit figurer dans le journal des modifications ; - utilisez `feat:` et `fix:` pour les fonctionnalités et corrections visibles par les utilisateurs ; - omettez le préfixe pour les refactorisations et tâches internes ; - marquez chaque modification incompatible avec un suffixe `!`. Rédigez des objets de commit qui nomment l’objectif visible par les utilisateurs et incluent la référence du ticket ou de la revue lorsque le projet l’exige. Lorsqu’une modification incompatible affecte plusieurs crates, divisez-la par crate si un seul message de commit ne peut pas décrire précisément tous les impacts. Placez la modification incompatible de l’API dans le premier commit et les adaptations en aval dans un commit suivant. Traitez les messages de commit comme des données d’entrée de la publication lorsque l’automatisation des publications en déduit les versions ou les journaux des modifications. Mettez à jour les guides de haut niveau, les instructions de contribution, les notes de développement, les registres d’état des crates et la documentation de stabilité dès que la modification du code les affecte directement. Utilisez comme référence de compatibilité la version de l’outil de référence disponible dans l’environnement CI principal, sauf si le projet définit une cible plus stricte. ## Parcourez la liste finale, de la couche du crate aux messages de commit Avant de terminer : 1. déterminez si la modification relève de l’infrastructure de bas niveau ou de l’interface de haut niveau ; 2. examinez les modèles établis dans des crates similaires ; 3. confirmez que la gestion des erreurs correspond au framework actuel de cette crate ; 4. vérifiez qu’aucun `unwrap()` n’a été introduit dans le code de production ; 5. contrôlez toutes les combinaisons de fonctionnalités et variantes de publication concernées ; 6. examinez séparément les appelants de la bibliothèque et les utilisateurs de la ligne de commande ; 7. exécutez les tests ciblés, de l’espace de travail, de parcours et de compatibilité selon les besoins ; 8. confirmez que les chemins orientés octets restent sans perte sur toutes les plateformes ; 9. examinez la nécessité mesurable des nouveaux clones, détachements, caches et mécanismes de synchronisation ; 10. mettez à jour la documentation directement concernée ; 11. confirmez que les messages de commit décrivent correctement l’impact sur le journal des modifications et les modifications incompatibles. Signalez tout ensemble de fonctionnalités, toute plateforme, toute comparaison avec la référence ou toute variante de publication non testés, en indiquant exactement le prérequis manquant. Ne prétendez pas à une compatibilité de tout l’espace de travail sur la base d’un test unitaire exécuté uniquement avec les fonctionnalités par défaut.