Files

T

Kantin-Petit c096fa9467 docs: conventions versioning + doc + paliers de risque (v0.2.0)

Pose les règles non négociables : SemVer + un-artefact-un-commit, pinning
des images, export JSON des workflows n8n ; gabarit de doc d'asset ;
paliers réversible/privilégié avec invariant anti-escalade ; schéma
d'architecture et invariants d'exposition. Ignore settings.local.json.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-23 00:59:25 +02:00

2.4 KiB

Raw Blame History

Versioning & documentation

Git est la source unique de vérité. Un artefact n'est "terminé" que s'il est à la fois versionné ET documenté. Règle non négociable (voir CLAUDE.md).

Qu'est-ce qu'un "artefact" ?

Tout ce qui est créé ou modifié et qui a un effet : workflow n8n, stack/compose Docker, code de l'orchestrateur, outil MCP, image Docker, doc d'asset.

SemVer (`vMAJEUR.MINEUR.PATCH`)

MAJEUR : changement incompatible (rupture d'API/contrat/comportement).
MINEUR : ajout rétro-compatible (nouvel outil, nouvelle capacité).
PATCH : correctif rétro-compatible, doc, durcissement sans rupture.
Phase 0.x : on tolère des ruptures sur le MINEUR (projet pré-1.0).

La version du dépôt est portée par CHANGELOG.md + un tag git vX.Y.Z. Les assets individuels (workflow, stack, outil) portent leur propre version dans leur en-tête de doc et dans la table assets (champ version).

Règle "un artefact = un commit"

Chaque création/modification d'artefact = un commit dédié :

message clair (Conventional Commits : feat:, fix:, chore:, docs:…),
bump de version approprié + entrée CHANGELOG.md,
la doc de l'artefact mise à jour dans le même commit.

Message type :

feat: <artefact> — <quoi> (vX.Y.Z)

<pourquoi / contexte>. Palier de risque : <réversible|privilégié>.

Images Docker

Tags épinglés et versionnés. Jamais :latest.
Idéalement épingler aussi le digest (image@sha256:…) pour l'immuabilité.
Tout bump d'image = commit + entrée CHANGELOG + note de rollback.

Workflows n8n

Exportés en JSON dans workflows-n8n/ — le dépôt fait foi, pas l'instance.
Convention de nommage : workflows-n8n/<slug>.v<MAJEUR.MINEUR.PATCH>.json.
Chaque workflow a une doc d'asset (voir asset-template.md).

Documentation d'un asset

Chaque artefact a une doc suivant docs/asset-template.md (rôle, entrées/sorties, dépendances, palier de risque, rollback). Un asset non documenté est incomplet et ne doit pas être considéré livré.

Lien avec le cycle "need review" (Phase 2+)

En Phase 4, CHLOVA devra committer + versionner + générer la doc d'un asset avant de le passer en "need review". La notification de review inclut la version + le lien commit + le lien doc (champs version, lien_commit, lien_doc de la table assets).

2.4 KiB Raw Blame History