Revue statique, conventions documentees, construction arm64 limitee aux versions et cache de couches

docs/CONVENTIONS.md

@@ -0,0 +1,80 @@
+# Conventions et revue avant livraison
+
+Ce fichier existe pour que le projet reste cohérent d'une version à l'autre, et pour qu'une
+anomalie soit trouvée sur le poste de développement plutôt qu'après soixante minutes de
+construction.
+
+## Revue avant chaque livraison
+
+Dans cet ordre, sans exception, y compris pour un correctif d'une ligne :
+
+```bash
+python -m ruff check .            # analyse statique, zéro signalement toléré
+python -m pytest -q               # la suite complète
+node --check enclume/static/*.js  # syntaxe des scripts
+sh -n docker/*.sh                 # syntaxe des scripts shell
+python -c "import yaml,glob;[yaml.safe_load(open(f)) for f in glob.glob('catalog/**/*.yml',recursive=True)]"
+docker compose -f compose.yaml config > /dev/null
+```
+
+Puis, dans un environnement vierge — c'est ce qui a manqué le jour où `requests` a cassé la
+CI :
+
+```bash
+python -m venv /tmp/vierge && /tmp/vierge/bin/pip install -r requirements.txt pytest
+/tmp/vierge/bin/python -m pytest -q
+```
+
+Et enfin la revue humaine, qui ne s'automatise pas :
+
+- toute ressource référencée par un gabarit existe-t-elle réellement ? (un test le vérifie
+  désormais, parce que l'oubli a déjà eu lieu)
+- une variable nouvelle est-elle présente dans `.env.example`, dans `compose.yaml` **et**
+  documentée ?
+- une valeur venant de l'utilisateur peut-elle contenir un caractère qui casse le format où
+  on l'insère ? Point-virgule pour le CLAPI, `@` et `:` pour une URL de connexion, guillemet
+  simple pour le shell. Trois incidents sur ce seul motif.
+- ce qui est écrit en base a-t-il traversé `strip_secrets` ?
+
+## Nommage
+
+| Objet | Règle | Exemple |
+|---|---|---|
+| Modules Python | français, minuscules, sans accent | `routes_donnees.py` |
+| Fonctions et variables | français, `snake_case` | `utilisateur_courant`, `_repertoire_catalogue` |
+| Classes | français, `PascalCase` | `Soumission`, `Prerequis` |
+| Variables d'environnement | préfixe `ENCLUME_`, majuscules | `ENCLUME_DB_MOTDEPASSE` |
+| Routes d'API | français, pluriel | `/api/soumissions`, `/api/partages` |
+| Identifiants HTML | français, `kebab-case` | `btn-serveur-ouvrir`, `filtre-statut` |
+| Fichiers statiques | français | `editeur.js`, `moderation.js` |
+| Tables | français, pluriel | `utilisateurs`, `partages` |
+| Packs du catalogue | `<famille>-<techno>[-<protocole>]` | `os-linux-snmp`, `hw-dell-idrac-snmp` |
+| Modèles d'hôte générés | `<Famille>-<Techno>-custom` | `OS-Linux-SNMP-custom` |
+| Modèles de service | `<Famille>-<Techno>-<Sonde>` | `OS-Linux-SNMP-Cpu` |
+| Images | `<registre>/enclume/<composant>` | `.../enclume/catalog-sync` |
+| Branches de soumission | `pack/<id>-<numéro>` | `pack/app-rabbitmq-7` |
+
+Les commentaires et la documentation sont en français. Le code source reste sans accents,
+par choix, pour éviter toute question d'encodage dans les conteneurs.
+
+## Versions
+
+Sémantique stricte, parce que la rétention Harbor et le retour arrière s'y appuient :
+
+- **correctif** (`1.1.2`) : rien de nouveau, rien qui change de nom
+- **mineure** (`1.2.0`) : fonctionnalité, nouvelle variable, migration de schéma
+- **majeure** (`2.0.0`) : rupture pour qui héberge déjà — variable supprimée, format de
+  projet incompatible
+
+Une migration de schéma n'ajoute que des colonnes et des tables. Une suppression attend la
+version suivante, sinon revenir à l'image précédente casse l'application.
+
+## Coût de construction
+
+L'arm64 passe par l'émulation QEMU et coûte l'essentiel du temps de construction. Il n'est
+donc produit **que sur un tag de version** ; un simple push sur `main` ne construit que
+l'amd64. Le cache de couches vit dans Harbor, à côté des images : tant que
+`requirements.txt` ne change pas, l'installation des dépendances est reprise du cache.
+
+Conséquence pratique : itérer sur `main` est rapide, publier une version reste lent. Autant
+grouper les corrections avant de taguer.