Conventions Git

Conventions Git de Codexia : messages de commit, signature, normalisation et vérifications automatiques. S'applique aux trois dépôts (telaria-doc, telaria, tlr-embeddings) ; telaria-doc en est le canon. Voir aussi : github.md (stratégie de branche), releases.md (workflow de release), git-hooks.md (hooks).

1. Messages de commit — Conventional Commits

Format : type(scope): sujet

• sujet : impératif présent, minuscule, sans point final (ex. « ajoute », « corrige »).
• scope (optionnel) : zone touchée (ex. ia, agents, deployment, docs-web).

Types utilisés :

Exemples (réels du dépôt) :

docs(ia): spec du Lot 0 — cœur RAG (socle headless)
ci: vérification automatique de la doc (liens + EOL)
docs: corrige les liens internes cassés et met les fiches RFC en stand-by

Pourquoi : lisibilité de l'historique, et base pour un changelog/versionnage automatisables plus tard. La validation du préfixe peut être imposée par un hook commit-msg (voir git-hooks.md).

Pied de commit (assistance IA) : les commits produits avec un assistant portent un trailer Co-Authored-By: Claude … <noreply@anthropic.com>.

Rappel inter-instances : un commit qui touche un fichier publié (specs/**, bundles/**, contrats d'interface, releases.md) doit s'accompagner d'une notification via les inboxes des autres dépôts de l'écosystème — voir le rituel détaillé dans releases.md § « Rituel inter-instances » et la topologie dans pilotage/ecosystem.md. Au tag, c'est obligatoire ; à chaque commit publié, c'est une bonne hygiène (skill /sync).

2. Normalisation (LF + UTF-8)

Le dépôt impose LF + UTF-8 via .gitattributes (cohérent avec AGENTS.md). Après ajout/modif de .gitattributes, renormaliser si besoin :

git add --renormalize .

3. Vérifications automatiques

Les contrôles de qualité de la doc sont automatisés (mêmes vérifs en local et en CI) :

• Script : scripts/check-doc-links.sh — liens Markdown internes (exclut inputs/legacy/, ignore les blocs de code et liens externes).
• CI : .github/workflows/docs-checks.yml — sur push develop/master (liens + EOL LF).
• Hook local (pre-push) : scripts/hooks/pre-push — échec rapide avant push. Activation une fois :

  git config core.hooksPath scripts/hooks
  

À répliquer dans telaria et tlr-embeddings (en adaptant les vérifs au contenu : lint PHP/Python, tests…).

4. Commits et tags signés (« Verified »)

Signer prouve l'authenticité des commits/tags et affiche le badge Verified sur GitHub (qualité/sécurité irréprochables — atout vitrine).

Signature SSH (recommandée, simple) :

# 1) générer une clé dédiée à la signature
#    créer ~/.ssh au préalable s'il n'existe pas (sinon : "No such file or directory")
mkdir -p ~/.ssh        # PowerShell : New-Item -ItemType Directory -Force "$HOME\.ssh"  —  cmd : mkdir "%USERPROFILE%\.ssh"
ssh-keygen -t ed25519 -C "Claude Code — signature" -f ~/.ssh/codexia_sign

# 2) configurer Git pour signer avec SSH
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/codexia_sign.pub
git config --global commit.gpgsign true
git config --global tag.gpgsign true

Puis ajouter la clé en « Signing Key » sur GitHub (Settings → SSH and GPG keys) — distincte d'une clé d'authentification.

Sur GitHub, lors de l'ajout : choisir « Signing Key » (et non « Authentication Key ») — c'est ce qui active la signature.

Identité signée : le badge Verified est rattaché au compte GitHub propriétaire, via l'e-mail du committer (git config user.email) — utiliser un e-mail vérifié du compte (souvent le noreply IDENT+pseudo@users.noreply.github.com). Le commentaire -C de la clé n'est qu'une étiquette (texte libre). L'assistant IA reste crédité par le trailer Co-Authored-By des commits, pas par la signature.

GPG (alternative classique) :

# 1) générer une clé (RSA 4096 ou ECC ; mettre le MÊME e-mail que sur GitHub)
gpg --full-generate-key

# 2) récupérer l'identifiant de la clé
gpg --list-secret-keys --keyid-format=long      # repérer la ligne "sec  rsa4096/<KEYID>"

# 3) exporter la clé publique (bloc à coller sur GitHub)
gpg --armor --export <KEYID>

# 4) configurer Git
git config --global user.signingkey <KEYID>
git config --global commit.gpgsign true
git config --global tag.gpgsign true

Puis GitHub → Settings → SSH and GPG keys → New GPG key → coller le bloc -----BEGIN PGP PUBLIC KEY BLOCK-----. Sous Windows : installer Gpg4win ; si Git ne trouve pas gpg, le pointer : git config --global gpg.program "C:/Program Files (x86)/GnuPG/bin/gpg.exe".

À retenir :

• Aucune des deux n'est obligatoire ; SSH est le plus simple (surtout sous Windows), GPG est la voie classique.
• L'e-mail de la clé doit correspondre à un e-mail vérifié de ton compte GitHub, sinon pas de badge Verified.
• La génération/déclaration de la clé est une action humaine (hors portée IA) ; une fois en --global, elle vaut pour les trois dépôts.
• Les tags de release doivent être annotés et signés.

Vérification locale (optionnel — pour que git log --show-signature affiche « Good signature ») :

printf '%s %s\n' "TON_EMAIL_GITHUB" "$(cat ~/.ssh/codexia_sign.pub)" > ~/.ssh/allowed_signers
git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers

Le badge Verified de GitHub ne dépend pas de ce fichier (il s'appuie sur la clé enregistrée + l'e-mail vérifié).

Documents liés

• Stratégie de branche (solo + IA) : github.md
• Workflow de release : releases.md
• Hooks Git : git-hooks.md