Conventions de développement

Convention commune à tous les projets (apps, sites, outils), outillée par git-flow (AVH) et Commitizen. L'infra a la sienne propre (trunk-based sur main) — ici on parle des projets de dev. Décision de fond : ADR-001 — Gitflow complet.

Outils sur le poste

sudo apt install git-flow pipx   # git-flow AVH
pipx install commitizen          # commandes cz / git-cz

Branches (Gitflow, piloté par `git flow`)

main ────●──────────────●────────▶  production, chaque merge = tag vX.Y.Z (CI)
          \            / \
release/1.1.0 ────────●   hotfix/1.1.1 ──▶ re-merge dans main ET develop
            \        /
develop ─●──●──●────●──────▶  intégration continue des features
          \    /
    feature/xxx

Je veux…	Commande
Démarrer une feature	`git flow feature start ma-feature`
La partager / ouvrir une PR	`git flow feature publish ma-feature` puis PR vers `develop` sur Forgejo
La terminer (merge dans `develop`)	`git flow feature finish ma-feature`
Préparer une release	`git flow release start $(cz bump --get-next)`
Terminer la release	`git flow release finish -n` puis `git push origin main develop`
Corriger la prod en urgence	`git flow hotfix start x.y.z` … `git flow hotfix finish -n`

Points clés :

Pas de tag à la main : release/hotfix finish se fait sans tag (-n, préconfiguré par le script de création) — c'est la CI qui pose le tag SemVer au merge sur main.
Le numéro de la branche release vient de cz bump --get-next : il est déduit des commits, pas choisi.
Une feature qu'on veut faire valider par la CI avant merge : publish + PR. Une retouche solo évidente : finish direct. Les deux sont conformes.

Chaque nouveau clone doit recevoir la config git-flow (le script de création la pose ; pour un clone ailleurs, copier ce bloc) :

git config gitflow.branch.master main
git config gitflow.branch.develop develop
git config gitflow.prefix.feature feature/ ; git config gitflow.prefix.release release/
git config gitflow.prefix.hotfix hotfix/  ; git config gitflow.prefix.support support/
git config gitflow.prefix.versiontag v
git config gitflow.release.finish.notag true ; git config gitflow.hotfix.finish.notag true

Messages de commit (Conventional Commits via Commitizen)

Écrire un commit : cz commit (ou git-cz) — Commitizen pose les questions et construit un message conforme. Un git commit -m direct reste possible s'il respecte le format type: description :

Type	Usage	Effet SemVer
`feat:`	nouvelle fonctionnalité	minor (1.2.0 → 1.3.0)
`fix:`	correction de bug	patch (1.2.0 → 1.2.1)
`feat!:` ou `BREAKING CHANGE:`	rupture de compatibilité	major (1.2.0 → 2.0.0)
`docs:` `test:` `refactor:` `perf:` `ci:` `chore:`	le reste	aucun

La CI vérifie chaque message (step commits-conformes) : hors format = build rouge.

Versions (SemVer automatique)

Personne ne choisit un numéro de version. Au merge d'une release ou d'un hotfix dans main, la CI (step version-semver) exécute cz bump :

lecture des commits depuis le dernier tag,
version déduite (règles du tableau ci-dessus),
tag vX.Y.Z + CHANGELOG.md mis à jour et poussés.

Le changelog est généré depuis les messages de commit : soigner la description d'un commit, c'est écrire le changelog.

Créer un nouveau projet

Une seule commande fait tout — repo Forgejo privé (main + develop), repo GitHub privé, miroir automatique, CI Woodpecker + secret, squelette local (.cz.toml, pipeline, .gitignore, config git-flow) :

cd ~/projets/infra
sops exec-env secrets/services.enc.env \
  './scripts/nouveau-projet.sh <nom> ~/projets/devapp "Description"'

Le miroir GitHub est à sens unique (Forgejo → GitHub) : on ne pousse jamais sur GitHub directement. Source de vérité : la forge.