Passa al contenuto principale

Convention: Branch Strategy & Release Process

Convention documentale — vincolante per tutto il codice nel monorepo akira.

Scopo​

Definire un processo Git semplice, prevedibile e compatibile con sviluppo agente-AI assistito (Toolbox runner notturno + sviluppo umano daytime).

1. Trunk-based development​

  • Branch principale: main (NON master).
  • main è sempre deployable: CI green, test passati, schema migrato.
  • Lavoro feature/task NON committed direttamente su main.
  • No long-lived feature branch — durata tipica task branch: 1-3 giorni.

2. Branch protection rules (GitHub)​

Configurato su main:

  • Require pull request before merging: ON.
  • Require approvals: 1 review approval minimo.
  • Dismiss stale approvals on new commits: ON.
  • Require status checks to pass: ON. Checks obbligatori:
    • ci/lint
    • ci/test-backend
    • ci/test-frontend
    • ci/build
  • Require branches to be up to date before merging: ON.
  • Require linear history: ON (no merge tangenti, no force-push).
  • Restrict force push: ON.
  • Restrict deletion: ON.

3. Task branch — convenzione di naming​

task/TASK-NN-descrizione-kebab-case

Esempi:

  • task/TASK-12-companies-crud-api
  • task/TASK-31-cdr-worker-nats-consumer
  • task/TASK-45-routing-topology-map-mockup

Regole:

  • Prefisso fisso task/.
  • TASK-NN riferimento al backlog Akira (numerazione progressiva).
  • Descrizione: kebab-case, max 5-7 parole, in inglese tecnico.

4. Workflow agente AI (Toolbox runner)​

L'agente AI lavora su task branch mai direttamente su main.

git checkout main
git pull --ff-only
git checkout -b task/TASK-NN-foo-bar
# ... lavoro agente: code + commit ...
git push origin task/TASK-NN-foo-bar
# apre PR via gh CLI

L'agente AI:

  • PUÒ commit + push su task/*.
  • NON PUÒ push su main.
  • NON PUÒ force-push neanche su task/* (eccetto rebase autorizzato esplicitamente).

5. Pull Request → Merge​

Apertura PR​

  • Titolo: [TASK-NN] Descrizione sintetica.
  • Body: template .github/pull_request_template.md (context, changes, testing).
  • Link al task del backlog.
  • Auto-assign reviewer in base al CODEOWNERS.

Review​

  • 1 approval minimo.
  • Per cambi schema DB: review obbligatoria da owner backend.
  • Per cambi mockup/UX: review obbligatoria da Massimo.

Merge​

  • Strategia: merge commit (no fast-forward, no squash).
  • Motivazione: linear history mantenuta dalle branch protection rules + il merge commit preserva il contesto della PR.
  • L'agente AI non può cliccare merge — solo il runner Toolbox o un umano autorizzato fa il merge.

Post-merge​

  • Branch task eliminato automaticamente (Automatically delete head branches GitHub setting ON).
  • CI su main runna deploy staging automatico.

6. Hotfix​

Per fix urgenti in produzione (bug critico, security patch):

git checkout main
git pull --ff-only
git checkout -b hotfix/<descrizione-breve>
# fix + commit + push
gh pr create --title "[HOTFIX] ..." --label hotfix

Regole hotfix:

  • Branch prefix: hotfix/.
  • PR può essere mergeata con review espressa (1 approval), anche se brevissima.
  • CI deve comunque passare (no skip).
  • Post-merge: deploy prod immediato (manual approve), poi tag v0.X.Y+hotfix.Z.
  • Postmortem entro 48h se hotfix è conseguenza di incident.

7. Release tag​

Tag semantico applicato al completamento di ogni fase del roadmap:

v0.<minor>.<patch>-fase-<N>

Esempi:

  • v0.1.0-fase-1 — completamento Fase 1 (backend MVP).
  • v0.2.0-fase-2 — completamento Fase 2 (signaling layer + HA).
  • v0.3.0-fase-3 — completamento Fase 3 (frontend complete).
  • v0.4.0-fase-4 — completamento Fase 4 (pilot customer onboarded).
  • v0.1.1-fase-1 — patch su Fase 1 dopo v0.1.0-fase-1.

Hotfix increment patch:

  • v0.2.0-fase-2 → v0.2.1-fase-2 (hotfix).

Versione v1.0.0 riservata a first paying customer in produzione.

Comando tag​

git checkout main
git pull --ff-only
git tag -a v0.1.0-fase-1 -m "Fase 1 complete: backend MVP"
git push origin v0.1.0-fase-1

GitHub Actions su tag push:

  • Build image taggata.
  • Push registry con tag.
  • Generate changelog draft GitHub Release.

8. Commit message convention​

Stile Conventional Commits:

<type>(<scope>): <subject>

[optional body]

[optional footer]

Types: feat, fix, refactor, chore, docs, test, perf, ci, build.

Esempi:

  • feat(companies): add CRUD API endpoints
  • fix(cdr-worker): handle NATS reconnect on timeout
  • docs(adr): add ADR-0008 Kamailio HA on Hetzner
  • chore(deps): bump fastapi to 0.115

Subject: imperative present, lowercase, no trailing period, max 72 char.

9. Schema migrations​

  • Migrazioni Alembic in apps/api/alembic/versions/.
  • File naming: <rev>_<descrizione_snake>.py (auto-generato).
  • Una migrazione = una PR (no merge di feature che cambiano schema in più migrazioni separate dentro la stessa PR senza giustificazione).
  • Migrazioni sono forward-only in produzione. Downgrade scritto solo per emergenza.
  • Migration nuova non può eliminare colonne usate dal codice ancora deployato — usare pattern expand/contract.

10. Checklist agente AI prima di aprire PR​

  • Branch parte da main aggiornato (git pull --ff-only recente).
  • Tutti i test locali passati (pnpm test + uv run pytest).
  • Lint pulito (ruff check, eslint).
  • Schema migration generata se sono cambiati modelli SQLAlchemy.
  • Aggiornata documentazione se cambio API o convention.
  • Commit message conformi a Conventional Commits.
  • PR body compila il template (context, changes, testing).