Modules Go : go.mod, go.sum et le suffixe de version majeure

Ce que c'est

La référence des modules Go définit un module comme un ensemble de paquets publiés ensemble, avec un fichier go.mod à sa racine nommant le chemin du module, la directive go (la version minimale de Go, imposée et non plus simplement indicative depuis Go 1.21), des lignes require et des directives facultatives replace, exclude, retract et toolchain. Les versions suivent Semantic Versioning 2.0.0 avec un préfixe v. La référence décrit la sélection de version minimale : la commande go parcourt le graphe des exigences et construit avec la version la plus élevée requise pour chaque module ; elle ne choisit jamais une version plus récente simplement parce qu'elle existe, si bien que la liste de build est reproductible à partir du seul go.mod. go.sum enregistre les empreintes cryptographiques de chaque module utilisé, vérifiées au téléchargement et, par défaut, par rapport à la base de sommes de contrôle publique sum.golang.org.

La règle sur laquelle butent les nouveaux venus est le suffixe de version majeure. La référence énonce la règle de compatibilité d'import (si un ancien paquet et un nouveau paquet ont le même chemin d'import, le nouveau paquet doit être rétrocompatible avec l'ancien) et exige donc que la version majeure 2 et au-delà porte le suffixe dans le chemin du module : example.com/lib/v2. Les versions v0 et v1 ne portent aucun suffixe ; v0 ne comporte aucune promesse de compatibilité. Les tags de version v2 ou supérieure sans fichier go.mod apparaissent avec +incompatible.

Pourquoi c'est important

pip et npm préfèrent la version autorisée la plus récente et ont besoin d'un fichier de verrouillage ou d'épinglage pour la reproductibilité ; Go résout vers la version la plus basse qui satisfait tout le monde et recalcule la même liste à chaque commande. Comme lib et lib/v2 sont des chemins d'import différents, les deux peuvent coexister dans le même build, et la montée d'une version majeure devient un chercher-remplacer d'imports plutôt qu'un conflit de résolveur.

Comment l'appliquer

• Exécuter go mod tidy après avoir modifié les imports ; cela ajoute les exigences manquantes, retire celles qui ne sont plus utilisées et met à jour go.sum ; valider les deux fichiers.
• Mettre à niveau une dépendance avec go get example.com/lib@v1.4.0 ; passer à une nouvelle version majeure en important le chemin suffixé.
• Lors de la publication de la v2 de son propre module, faire se terminer la ligne module par /v2 avant de poser le tag ; le billet de blog sur les modules v2 recommande un sous-répertoire de version majeure (v2/go.mod) plutôt que des branches séparées.
• N'utiliser replace que dans le module principal pour le développement local ; la référence indique qu'il est ignoré dans les fichiers go.mod des autres modules.
• Préférer retract à la suppression d'un mauvais tag ; le tag reste dans la base de sommes de contrôle.

Pièges

Poser le tag v2.0.0 sur un module dont le chemin ne porte pas le suffixe fait rejeter la version par la commande go. La directive go est une exigence stricte depuis Go 1.21 : une chaîne d'outils plus ancienne que la version déclarée bascule vers une plus récente ou refuse de construire, plutôt que de simplement avertir. go.sum n'est pas un fichier de verrouillage : il vérifie ce que la sélection de version minimale a choisi.