Versioning sémantique

Versioning sémantique

1) Qu'est-ce que BouVer et pourquoi il est nécessaire

• MAJOR - Modifications incompatibles.
• MINOR est une nouvelle fonctionnalité compatible avec l'API.
• PATCH - corrections de défauts réversibles.

Objectif : négocier la stabilité des contrats et réduire le coût des mises à jour.

2) Format de version

• `MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD]`

`1. 4. 7 '- sortie stable.
`1. 5. 0-rc. 2 '- pré-sortie (version candidate n ° 2).
`2. 0. 0+linux. arm64 '- métadonnées de build (n'affectent pas la comparaison des versions).

1. On compare d'abord 'MAJOR', puis 'MINEUR', puis 'PATCH'.

2. Les versions pré sont inférieures à la version stable correspondante : '1. 2. 0-rc. 1 < 1. 2. 0`.

3. Les métadonnées de construction ('+...') n'affectent pas l'ordre : '1. 2. 0+001 == 1. 2. 0`.

3) Ce qui compte breaking change

• Supprimer/renommer/changer la signature des méthodes/endpoints publics.
• Modifier le format d'entrée/sortie (schéma JSON, types).
• Modification des contrats d'erreurs (codes/structures).
• Modifier les side-effects/SLA (par exemple, limites strictes ou nouveaux champs obligatoires).

Non breaking (lorsqu'il est correctement implémenté) : ajout de champs facultatifs, extension enum avec de nouvelles valeurs (si le client les ignore), de nouveaux endpoints, de nouveaux drapeaux avec des défauts qui n'affectent pas les appels en cours.

4) Pré-sorties et stratégies de canal

• Étiquettes : 'alpha', 'beta', 'rc'. Exemple : '2. 3. 0-beta. 3`.
• Chaînes : nightly → alpha → beta → rc → stable.
• Stratégie : Les pré-versions ne doivent pas être considérées comme des dépendances transitives pour les assemblages prod par défaut.

5) Gammes de versions et précision des dépendances

5. 1 Node/npm (BouVer par défaut)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0 '(autorise MINOR/PATCH, fixe MAJOR).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0 '(autorise PATCH au sein de MINOR).
`1. 4. x 'est tout paiement en 1. 4.
Pin exact : '1. 4. 2`.

5. 2 Python (PEP 440, pip)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0 'sont des limites explicites.

5. 3 Maven/Gradle (Java)

`[1. 4,2. 0) - inclusivement/exclusivement.
Des coups de pied stricts sont recommandés pour les artefacts critiques.

5. 4 Go modules

Toujours des tags'vMAJOR. MINOR. PATCH ';' v2 + 'nécessite le suffixe du module '/v2'.

Recommandation : pour les applications - pins exacts (constructions réparables). Pour les bibliothèques, des gammes caret (faciliter les mises à jour sans cassure).

6) CHANGELOG и Conventional Commits

Un journal des changements structuré améliore la transparence.

feat(payments): add PIX refund endpoint fix(api): correct 400 → 422 on invalid payload perf(cache): reduce p99 by 20%
refactor(core): extract rule engine docs: update API usage examples chore(deps): bump lodash to 4. 17. 21 feat!: remove legacy webhook v1 (BREAKING CHANGE:...)

Типы: `feat`, `fix`, `perf`, `docs`, `refactor`, `chore` и т. д.
Un point d'exclamation ou un bloc 'BREAKING CHANGE' annonce une augmentation MAJOR.
CHANGELOG est généré à partir de l'histoire des commits (release-notes bots).

7) Politique de versioning pour l'API

APIs publiques : BouVer strict ; breaking → MAJOR.
HTTP/REST : versioning par URL/en-tête : '/v1/... ', '/v2/...' ou 'Accept : application/vnd. org. service. v2+json`.
Schémas JSON : extensions mineures - nouveaux champs facultatifs ; major - supprimer/modifier les obligatoires.
gRPC/Protobuf : ajouter de nouveaux champs avec de nouveaux numéros ; n'utilisez pas les numéros de champ ; supprimer → deprecate plutôt que de « casser » les deprecate existants.

8) Schémas de données et de migration

Les migrations OBD sont synchronisées avec les versions de l'application : 'app @ 1. 8. 0 'nécessite' schema @ 1. 8. x`.
Pour le breaking des changements de schéma - phases : expand (ajouter), migrate, contract (supprimer). N'augmentez la version MAJOR que lorsque vous supprimez l'ancien contrat.
Maintenez la double écriture/lecture pendant la migration.

9) Monorépo et microservices

Multi-package : chaque paquet est son propre 'MAJOR. MINOR. PATCH`; un cycle racine générique de libération uniquement pour les méta-artefacts.

• Versions indépendantes (Lerna/Changesets) - renforce l'isolation.
• Lock-step est plus facile à communiquer, mais plus faux MAJOR.
• Pour les microservices, fixez les contrats (OpenAPI/Protobuf) avec une version distincte : 'contract @ 2. 1. 0 ', le service la suit.

10) Automatisation des sorties en CI/CD

• `fix` → `PATCH`, `feat` → `MINOR`, `!`/`BREAKING` → `MAJOR`.

yaml
Pseudo-workflow steps:
- run: npx semantic-release
- run: git tag v$NEW_VERSION && git push --tags
- run: cosign sign ghcr. io/org/app:v$NEW_VERSION

La génération CHANGELOG, la publication de la sortie, la mise à jour des dépendances dans GitOps-repo, la vérification que 'main' indique toujours la dernière balise stable.

11) Politique de privation (politique de déprection)

Annonce : marquez la fonctionnalité comme deprecated dans la version MINOR, laissez un délai EOL (par exemple 90 jours).
Observabilité : Loger l'utilisation d'endpoints obsolètes avec un contexte user/tenant.
Suppression : dans le MAJOR suivant. Documentez le chemin de migration.

12) Exemples et modèles

12. 1 Expression régulière de validation BouVer

regex
^(0    [1-9]\d)\.(0    [1-9]\d)\.(0    [1-9]\d)(?--([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))? (?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))?$

12. 2 Exemples de comparaisons

`1. 2. 3` < `1. 10. 0 '(comparaison MINOR).
`2. 0. 0-rc. 1` < `2. 0. 0`.
`1. 2. 3+build. 5` == `1. 2. 3`.

12. 3 Politique de dépendance (exemple YAML)

yaml policy:
libraries:
default_range: "^MAJOR. MINOR. PATCH"
pin_security_critical: true services:
pin_exact: true allow_prerelease_in_nonprod: true api_contract:
require_same_minor: true forbid_major_mismatch: true

13) Anti-modèles

Utilisation de « latest »/balises flottantes dans la vente.
Augmentation de MAJOR sans véritable rupture (« versions marketing »).
Modifications cachées sous l'apparence « PATCH ».
Pré-versions dans les dépendances transitives des applications pro.
Modifier l'artefact sans nouvelle étiquette (versions mutables).
Versions incohérentes du code et du schéma OBD.

14) Chèque de mise en œuvre (0-45 jours)

0-10 jours

Acceptez BouVer comme norme obligatoire, approuvez les critères de rupture.
Activez les comités conventionnels et le modèle PR avec le champ 'BREAKING CHANGE'.

11-25 jours

Connectez semantic-release/changesets, auto-génération CHANGELOG.
Configurez la signature et la publication des artefacts avec la balise 'vX. Y.Z`.

26-45 jours

Entrez la politique de deprection et la télémétrie d'utilisation des API obsolètes.
Synchronisez les versions des contrats (OpenAPI/Proto) et des services.
Interdire « latest » et les balises mutables au niveau de la politique (ORA/règlement CI).

15) Métriques de maturité

% d'artefacts publiés uniquement sur la balise BouVer.
Temps de migration moyen entre les versions MINOR.
Nombre d'incidents dus à des modifications cachées.
Couverture des comités conventionnels dans les référentiels (> 95 %).
Proportion de dépendances sans fourchettes flottantes dans la vente (> 90 %).

16) Quand SamVer n'est pas nécessaire

Prototypes rapides internes sans consommateurs externes (le versioning daté convient).
Données/modèles avec dattes expérimentales (meilleure version Model/Schema avec compatibilité au niveau des convertisseurs).
Paquets de contenu sans API publique stable.

17) Conclusion

BouVer est un contrat de confiance entre le fabricant et le consommateur. Définissez clairement ce qui brise la compatibilité, automatisez la reconnaissance des types de libération et la publication des artefacts, gérez un CHANGELOG transparent et respectez la politique de privation. Les mises à jour deviendront alors routinières, prévisibles et sécurisées - et l'infrastructure et l'API se développeront sans choc pour les entreprises.