Aller au contenu

ADR 0001 — Distribution via submodule git

Contexte

Le kit doit être consommé par plusieurs projets, chacun pouvant rester sur une version, tirer des mises à jour à son rythme, ou rollback en cas de régression. Le mécanisme de distribution doit être :

  • Versionnable au niveau du projet consommateur (sha précis connu).
  • Auditable : la diff entre deux versions du kit doit être visible.
  • Sans dépendance à un registry privé (npm enterprise, registry privé docker).
  • Sans télémétrie ni appel réseau obligatoire au runtime.

Options envisagées

  1. Paquet npm privé — publié sur un registry interne.
  2. Image Docker — le kit dans un conteneur exécuté en side-car.
  3. Copier-coller dans chaque projet — pas de mécanisme de mise à jour.
  4. Submodule git — le kernel vit dans .sdeg/, pointant vers un sha précis.

Décision

Retenu : submodule git.

Le projet consommateur ajoute sdeg-kernel comme submodule dans .sdeg/. Le fichier .gitmodules encode l'URL et le sha. Les mises à jour se font via git submodule update --remote.

Conséquences

Positives :

  • Aucun registre externe à maintenir.
  • La version du kernel est visible dans l'historique git du projet consommateur (le sha apparaît dans les diffs).
  • Rollback immédiat : git checkout <sha> dans le submodule.
  • Pas de runtime réseau : le kit marche offline.

Négatives :

  • Les submodules ont mauvaise réputation (UX git moins intuitive que npm install).
  • Les utilisateurs doivent git submodule update --init --recursive après un clone.
  • La CI doit savoir tirer les submodules.

Neutres :

  • Le bootstrap copie les skills/hooks/templates hors de .sdeg/ vers leurs emplacements d'usage. C'est une duplication volontaire pour que les outils (Copilot, Claude) trouvent les fichiers à leur emplacement canonique.

Références