Modifier une bibliothèque Go publique sans casser le code de ses utilisateurs

## Avant de modifier le code, vérifier les versions de Go prises en charge et les branches Considérez l’exactitude, la rétrocompatibilité et les spécifications externes applicables comme des critères d’acceptation prioritaires. Avant de modifier le code, déterminez : - la branche de développement active et la branche stable de maintenance la plus récente ; - la version minimale de Go prise en charge pour les utilisateurs ; - la version plus récente de Go et la chaîne d’outils nécessaires au développement du dépôt ; - les paquets qui constituent l’API publique couverte par la garantie de compatibilité ; - les paquets internes ou expérimentaux importables qui ne sont pas couverts par les garanties de versionnage sémantique, mais qui sont néanmoins utilisés en pratique. Ne supposez pas que « non couvert par le versionnage sémantique » signifie « modifiable de manière incompatible sans risque ». Signalez toute modification de comportement ou d’API susceptible de perturber de vrais utilisateurs. Conformément à la politique du dépôt, dirigez les nouvelles fonctionnalités vers la branche de développement et les correctifs vers la branche stable appropriée. Dans les paquets publics, évitez les API de la bibliothèque standard et les fonctionnalités du langage postérieures à la version minimale déclarée de Go. Maintenez le contrôle de compatibilité exécutable dans la compilation afin que les fonctionnalités non prises en charge échouent tôt, avant d’atteindre les utilisateurs. ## Lancer les vérifications et les tests avec les outils du projet Utilisez l’exécuteur de tâches et l’outil de formatage définis par le projet au lieu de leur substituer des commandes familières. La cible de vérification par défaut doit combiner compilation, contrôles de licence, de format et de modules, analyse statique et tests rapides. Maintenez deux niveaux de tests : - une suite courte avec détection des accès concurrents pour obtenir un retour rapide ; - une suite d’intégration complète comprenant les dépendances de service requises par le dépôt et un délai d’expiration prolongé. Si les tests d’intégration partagent l’état du serveur, exécutez la suite complète de manière séquentielle et n’augmentez jamais le parallélisme dans le seul but de réduire la durée d’exécution. Permettez la configuration des points de terminaison des services tout en conservant une valeur locale par défaut documentée. Exécutez des contrôles d’analyse statique ou de compilation sur plusieurs architectures lorsque le comportement de bas niveau dépend de l’architecture. Vérifiez en particulier les cibles 32 bits lors de l’utilisation d’accès atomiques : les champs 64 bits accédés atomiquement doivent présenter un alignement sûr, par exemple en étant placés au début d’une structure ou en utilisant des enveloppes atomiques typées. ## Suivre les modèles de la bibliothèque pour les erreurs et l’API publique Suivez les modèles établis dans le dépôt : - enveloppez les erreurs avec du contexte à l’aide de `%w` et comparez-les avec `errors.Is` ou `errors.As`, plutôt que de rechercher une correspondance dans le texte du message ; - utilisez `context.Context` comme premier argument de toute méthode publique bloquante et dérivez les échéances du contexte de l’appelant, au lieu de créer des temporisateurs indépendants en temps réel qui lui feraient concurrence ; - utilisez des types de document ordonnés pour les commandes ou les données dont l’ordre des clés est important, des types apparentés aux tables d’association uniquement lorsque l’ordre est réellement sans importance, et des représentations de bas niveau fondées sur des séquences d’octets seulement dans des chemins critiques dûment justifiés ; - écrivez les mots en entier dans les identifiants exportés, ajoutez à chaque identifiant exporté un commentaire de documentation qui prend son nom pour sujet et suivez le modèle de constructeur ou de mutateur du projet pour les nouvelles options. Préservez l’organisation actuelle des paquets et les décisions de migration. Ne rétablissez pas des chemins d’importation retirés ni des abstractions publiques obsolètes. Lorsque la surveillance des commandes ou les diagnostics peuvent observer des échanges d’authentification, ajoutez les commandes qui manipulent des identifiants à la politique de masquage avant d’exposer les événements. Les dépendances natives et les étiquettes de compilation propres à une fonctionnalité doivent rester explicites dans les instructions de configuration et de test. ## Séparer tests unitaires et d’intégration, et lancer ceux que le changement exige Placez les tests unitaires à côté de l’implémentation et les tests d’intégration dans la zone d’intégration du dépôt. Utilisez les assistants d’assertion du projet et préférez les vérifications sémantiques, telles que `ErrorIs`, aux assertions fondées sur des sous-chaînes. Pour le comportement d’intégration, utilisez le banc d’essai standard sensible à la topologie pour configurer le déploiement, injecter des points de défaillance et capturer les événements. Conservez les données de test issues des spécifications dans l’emplacement prévu, initialisez les sous-modules ou les sources de données nécessaires après le clonage et numérotez les cas de test descriptifs conformément à la spécification applicable lorsque la traçabilité est importante. Avant la revue, exécutez la cible de vérification par défaut. Exécutez la suite complète de manière séquentielle lorsque la modification touche au comportement d’intégration ou à l’état partagé du serveur. La réussite d’un test unitaire limité ne constitue pas une preuve suffisante pour des modifications sensibles à plusieurs architectures, à la compatibilité ou aux spécifications. ## Préparer une demande de fusion avec les résultats des tests et l’impact sur la compatibilité Utilisez le préfixe d’élément de travail requis dans les messages de commit et les titres de demande de fusion. La demande de fusion doit expliquer le comportement visible par l’utilisateur, l’incidence sur la compatibilité, les preuves de test et le choix de la branche. Ajoutez les preuves propres à la modification : - pour une modification de l’API publique, générez le rapport d’API du dépôt et joignez-le à la demande de fusion ; - pour une modification incompatible visible par l’utilisateur, mettez à jour le guide de migration correspondant ; - pour un travail de conformité à une spécification, citez l’exigence exacte satisfaite par l’implémentation ; - pour une modification d’un paquet expérimental importable, signalez explicitement les incompatibilités, même si le versionnage sémantique ne l’exige pas. Ne présentez pas une modification comme prête au seul motif qu’elle se compile localement. Pour être prête, elle doit réussir les contrôles par défaut du dépôt ainsi que tous les contrôles de compatibilité, d’intégration, d’API et de spécification directement applicables.