Technique Docs

Appearance

Politique SemVer et Releases ​

Problem Statement ​

Le projet SK_CAPACITOR_DISPLAY et son bridge TV evoluent rapidement. Sans regles strictes de versionnement, les equipes applicatives, host et operationnelles ne peuvent pas evaluer l'impact d'une livraison (compatible, additive, ou cassante) avant de deployer.

Solution Overview ​

Le projet applique SemVer (MAJOR.MINOR.PATCH) avec une chaine de release automatisee basee sur semantic-release.

  • PATCH: correction backward-compatible (fix:)
  • MINOR: ajout backward-compatible (feat:)
  • MAJOR: changement incompatible (feat!: ou BREAKING CHANGE:)

Les tags Git sont standardises en vX.Y.Z uniquement.

Scope du contrat versionne ​

La politique SemVer couvre les interfaces exposees aux consommateurs:

  • Bridge unifie (TV_API_REQUEST / TV_API_RESPONSE)
  • Contrats et fixtures valides par npm run test:contract
  • Structure de donnees attendue par les hosts et l'application
  • Comportements publics documentes (config, protocoles, endpoints internes contractuels)

Les refactorings internes sans impact contractuel ne doivent pas forcer un MAJOR.

Regles de classification ​

PATCH ​

  • Correctif sans changement de contrat public
  • Stabilisation performance ou robustesse sans impact integrateur
  • Ajustement tests/docs sans impact runtime externe

MINOR ​

  • Nouvelle capacite additive backward-compatible
  • Nouveau champ optionnel dans une charge utile
  • Nouveau comportement active de maniere non disruptive

MAJOR ​

  • Suppression/renommage d'un champ attendu
  • Changement de semantics d'une commande bridge existante
  • Modification necessitant adaptation obligatoire cote host/integrateur

Conventional Commits ​

Les commits doivent suivre type(scope): description.

  • fix(scope): ... -> PATCH
  • feat(scope): ... -> MINOR
  • feat(scope)!: ... ou footer BREAKING CHANGE: -> MAJOR
  • docs, chore, refactor, test, style, ci -> pas de release par defaut

Validation automatique des messages via commitlint en CI.

Release Automation (main) ​

Le workflow Release est execute uniquement sur main et utilise runs-on: self-hosted.

Pipeline avant publication:

  1. npm ci
  2. npm run lint
  3. npm run lint:logs
  4. npm run lint:preferences
  5. npm run format:check
  6. npm run typecheck
  7. npm test
  8. npm run build
  9. npm run test:contract
  10. semantic-release

En cas d'echec d'un controle qualite, aucune release n'est publiee.

Changelog officiel ​

Le changelog officiel est CHANGELOG.md a la racine du projet. Il est mis a jour automatiquement par semantic-release a chaque release.

docs/technique/evolution/changelog.md reste une archive editoriale historique.

Bootstrap et migration ​

  • Tag de demarrage recommande: v28.2.2 sur l'etat de reference
  • Les tags historiques avec suffixe build sont conserves pour tracabilite
  • Toutes les nouvelles releases utilisent uniquement vX.Y.Z

Troubleshooting ​

  • Si aucune release ne sort: verifier le type de commit (fix, feat, BREAKING CHANGE)
  • Si semantic-release echoue: verifier les permissions GitHub (contents: write)
  • Si le changelog ne bouge pas: verifier la presence du plugin @semantic-release/changelog
  • Si test:contract echoue: aligner fixtures locales avec le contrat versionne

Compatibility ​

  • Node.js >= 20.9.0
  • GitHub Actions avec runner self-hosted
  • Branche de release: main uniquement

Performance and Risk ​

  • Impact principal: allongement du job de release (checks qualite complets)
  • Benefice: suppression des erreurs humaines de bump/version/tag/changelog
  • Risque principal: commit messages non conformes; mitige via workflow Commitlint