Releases

Ce document décrit le workflow de release pour les projets Codexia.

Référence externe (GitFlow) :

• https://nvie.com/posts/a-successful-git-branching-model/

Principes

• develop est la branche d’intégration.
• master est figée et ne reçoit que les releases.
• Les releases sont taguées sur master (format vX.Y.Z, ex. : v1.2.0).
• En développement, Composer peut pointer vers dev-develop.
• En production, Composer doit pointer vers un tag de release.
• Mode solo + IA : le report develop → master se fait en merge direct fast-forward (--ff-only), sans PR (choix assumé — voir github.md). master n'est pas protégée ; l'historique reste linéaire.
• Tags immuables : un tag publié n'est jamais redéplacé ni réécrit. Si un numéro est déjà pris (même par un tag « fantôme »), prendre le suivant (ex. : v0.3.0 occupé → v0.4.0).

Numérotation des versions

• Majeure : modification majeure (feature majeure ou changement technologique significatif).
• Mineure : ajout ou modification de features, et/ou bugfixs.
• Révision : corrections mineures (bugfixs, typos, ajustements légers).

Nommage des branches

• features/<id>-<slug> pour les nouvelles fonctionnalités.
• hotfix/<id>-<slug> pour les correctifs urgents.
• <id> correspond à un identifiant de ticket quand il existe (sinon à définir).

Procédure

1. Fusionner les branches de travail dans develop.
2. Pousser develop (historique public à jour).
3. Vérifier develop (tests, revue, documentation).
4. Mettre à jour CHANGELOG.md.
5. Reporter develop vers master.
6. Créer un tag de version sur master.
7. Nettoyage des branches : Supprimer les branches de tickets fusionnées qui sont liées à une version mineure inférieure à N-1 (ex: à la sortie de la 0.3, on supprime les branches de la 0.1).
8. Back-merge master vers develop si nécessaire.
9. Rituel inter-instances (cf. § dédié ci-dessous).

Rituel inter-instances (à chaque tag)

S'applique à tout dépôt de l'écosystème (telaria, telaria-doc, tlr-embeddings, tlr-rag). Source de vérité de la topologie : pilotage/ecosystem.md. Skill associé : /sync.

À la sortie d'un tag, avant de clore la session :

1. Mettre à jour la cartographie quand la version publiée touche un contrat ou un composant cité :
   • pilotage/coordination.md — journal des décisions et jalons.
   • pilotage/ecosystem.md — colonne « Version courante » des dépôts concernés.
   • specs/architecture.md — uniquement si l'architecture publique évolue.
2. Notifier les autres instances via leurs inboxes : <autre-dépôt>/memory/.../inbox-from-<moi>.md. Message bref, daté, numéroté #N, structuré ✅/🚀/🔔 (cf. gabarit du skill /sync).
3. Mettre à jour sync-state.json (last_pushed_sha_to.<destinataire> = SHA du tag).

Déclencheurs typiques : changement de contrat d'interface, nouvelle release de bundle/microservice, modification d'un fichier publié (specs/**, bundles/**, releases.md).

Did you know ?

Un merge "fast-forward" se produit quand master n'a aucun commit propre depuis le dernier point commun avec develop. Dans ce cas, Git avance simplement master au dernier commit de develop, sans créer de commit de merge.

GitHub Releases (optionnel)

Avantages :

• Page dédiée par version, facile à partager.
• Notes de version lisibles, avec possibilité d'attacher des assets.
• Notifications automatiques aux abonnés du dépôt.
• Intégrations simples avec CI/CD pour publier des artefacts.
• Visibilité claire des versions taguées.

Inconvénients / risques :

• Dépendance à GitHub (UI, permissions, disponibilité, politique).
• Les assets sont hébergés chez GitHub (verrouillage potentiel).
• Processus couplé à une fonctionnalité propriétaire.
• Migration hors GitHub peut faire perdre l'historique des Releases.

Recommandations (si on utilise GitHub Releases) :

• Le tag git et le CHANGELOG.md restent la source de vérité.
• Générer les notes de release à partir du CHANGELOG.md.
• Conserver les artefacts importants dans un stockage indépendant si nécessaire.
• Garder un workflow de release qui fonctionne sans GitHub (tag + changelog suffisent).

Prérequis (avant release)

• Un README.md est présent à la racine, avec un minimum de contexte sur le dépôt.
• Un CHANGELOG.md est présent à la racine, à jour.
• develop est propre (pas de modifications locales).
• Les tests/validations attendus sont passés.
• Protection de master : non requise en mode solo (merge direct assumé, cf. github.md) ; à activer si une équipe ou une CI rejoint.

Checklist (IA autonome)

1. Vérifier la branche courante (develop) et l'état Git (clean).
2. Valider que README.md et CHANGELOG.md existent.
3. Mettre à jour CHANGELOG.md pour la release.
4. Pousser develop.
5. Merger develop vers master (git merge --ff-only develop).
6. Vérifier que le numéro n'est pas déjà pris (git tag et git ls-remote --tags origin) ; sinon prendre le suivant. Puis créer un tag annoté sur master (format vX.Y.Z, ex. : v0.4.0).
7. Pousser master et le tag.
8. Revenir sur develop.