smavs/docs/development/git-workflow.md

# 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.