repository: aggiunta di documentazione base

docs/development/git-workflow.md

@@ -0,0 +1,380 @@
+# SMAVS Git Workflow
+
+**Version:** 1.0.0
+**Status:** Approved
+**Project:** Spiral – SMAVS Composition Engine
+
+---
+
+# 1. Scopo
+
+Questo documento definisce il workflow Git ufficiale del framework **SMAVS (Su Misura Al Vostro Sistema)**.
+
+L'obiettivo è garantire:
+
+- una cronologia pulita;
+- commit consistenti;
+- sviluppo incrementale;
+- tracciabilità delle modifiche;
+- integrazione continua affidabile.
+
+Tutti i contributi al progetto devono rispettare le regole definite nel presente documento.
+
+---
+
+# 2. Branch Principali
+
+Il repository utilizza i seguenti branch.
+
+## main
+
+Contiene esclusivamente codice stabile.
+
+Ogni commit presente su `main` deve:
+
+- compilare;
+- superare tutti i test;
+- rispettare la Software Architecture Specification;
+- rispettare la Implementation Roadmap.
+
+---
+
+# 3. Workflow di Sviluppo
+
+Ogni nuova attività deve seguire il seguente flusso.
+
+```
+Aggiornamento repository
+
+↓
+
+Sviluppo
+
+↓
+
+git status
+
+↓
+
+git add
+
+↓
+
+pre-commit
+
+↓
+
+Commit
+
+↓
+
+Push
+
+↓
+
+Continuous Integration
+
+↓
+
+Merge
+```
+
+---
+
+# 4. Ciclo di Sviluppo
+
+Prima di iniziare una nuova attività:
+
+```bash
+git pull origin main
+```
+
+Durante lo sviluppo:
+
+```bash
+git status
+```
+
+Aggiungere le modifiche:
+
+```bash
+git add .
+```
+
+Verificare il codice:
+
+```bash
+python -m pre_commit run --all-files
+```
+
+Creare il commit:
+
+```bash
+git commit -m "<ambito>: <azione>"
+```
+
+Pubblicare le modifiche:
+
+```bash
+git push origin main
+```
+
+---
+
+# 5. Convenzione dei Commit
+
+Ogni commit deve seguire il formato:
+
+```
+<ambito>: <azione>
+```
+
+---
+
+## Repository
+
+```
+repository: inizializza struttura
+repository: aggiorna readme
+repository: aggiunge licenza
+repository: configura gitignore
+```
+
+---
+
+## Tooling
+
+```
+tooling: configura ruff
+tooling: configura mypy
+tooling: configura pytest
+tooling: configura mkdocs
+```
+
+---
+
+## Continuous Integration
+
+```
+ci: configura pipeline
+ci: aggiorna workflow
+```
+
+---
+
+## Shared Kernel
+
+```
+shared: implementa identifier
+shared: implementa version
+shared: implementa timestamp
+```
+
+---
+
+## Contracts
+
+```
+contracts: aggiunge compose request
+contracts: implementa execution plan
+```
+
+---
+
+## Models
+
+```
+models: implementa project
+models: implementa branding
+```
+
+---
+
+## Protocols
+
+```
+protocols: implementa analyzer
+protocols: implementa resolver
+```
+
+---
+
+## Analysis
+
+```
+analysis: implementa validator
+analysis: implementa mapper
+```
+
+---
+
+## Knowledge
+
+```
+knowledge: implementa registry
+knowledge: implementa planner
+```
+
+---
+
+## Composition
+
+```
+composition: implementa renderer
+composition: implementa assembler
+```
+
+---
+
+## Engine
+
+```
+engine: implementa pipeline
+engine: implementa orchestrator
+engine: implementa smavs engine
+```
+
+---
+
+## Application
+
+```
+application: implementa compose use case
+```
+
+---
+
+## API
+
+```
+api: aggiunge router compose
+api: implementa dto artifact
+```
+
+---
+
+## Modules
+
+```
+modules: aggiunge hero
+modules: aggiunge navbar
+```
+
+---
+
+## Tests
+
+```
+tests: aggiunge test identifier
+tests: aumenta coverage
+```
+
+---
+
+## Documentation
+
+```
+docs: aggiorna architettura
+docs: aggiunge guida moduli
+```
+
+---
+
+# 6. Regole per i Commit
+
+Ogni commit deve:
+
+- rappresentare una singola modifica logica;
+- essere atomico;
+- compilare correttamente;
+- superare tutti i controlli del pre-commit.
+
+Non sono consentiti commit contenenti codice non funzionante.
+
+---
+
+# 7. Pre-Commit
+
+Prima di ogni commit deve essere eseguito:
+
+```bash
+python -m pre_commit run --all-files
+```
+
+Tutti gli hook devono risultare verdi.
+
+---
+
+# 8. Continuous Integration
+
+Ogni push attiva automaticamente la pipeline di Continuous Integration.
+
+La pipeline verifica:
+
+- Ruff
+- MyPy
+- Pytest
+- Coverage
+
+Il branch `main` deve rimanere sempre stabile.
+
+---
+
+# 9. Pull Request
+
+Ogni Pull Request deve:
+
+- superare la CI;
+- rispettare i Coding Standards;
+- rispettare la SAS;
+- rispettare la Roadmap.
+
+---
+
+# 10. Versioning
+
+Il progetto utilizza Semantic Versioning.
+
+```
+MAJOR.MINOR.PATCH
+```
+
+Esempi
+
+```
+0.1.0
+0.2.0
+1.0.0
+1.1.0
+1.1.1
+```
+
+---
+
+# 11. Regole Fondamentali
+
+Le seguenti regole sono considerate invarianti del workflow.
+
+1. Il branch `main` deve rimanere sempre stabile.
+
+2. Ogni commit deve rappresentare una singola modifica logica.
+
+3. Tutti i commit devono rispettare la convenzione ufficiale.
+
+4. Nessun commit deve aggirare il pre-commit.
+
+5. Nessun push deve ignorare la Continuous Integration.
+
+6. Ogni modifica deve rispettare la Software Architecture Specification.
+
+7. Ogni modifica deve rispettare la Implementation Roadmap.
+
+8. Ogni modifica deve rispettare i Coding Standards.
+
+---
+
+# 12. Stato della Specifica
+
+Questo documento costituisce il workflow Git ufficiale del framework SMAVS.
+
+Ogni contributo al progetto deve rispettare integralmente le regole qui definite.