Kantin-Petit
c096fa9467
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>
53 lines
2.4 KiB
Markdown
53 lines
2.4 KiB
Markdown
# 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).
|