# Contributing

**Version:** 1.0.0
**Status:** Approved
**Project:** Spiral – SMAVS Composition Engine

---

# 1. Scopo

Questo documento definisce le regole ufficiali per contribuire allo sviluppo del framework **SMAVS (Su Misura Al Vostro Sistema)**.

L'obiettivo è garantire che ogni modifica:

- sia coerente con l'architettura;
- rispetti gli standard di qualità;
- mantenga la stabilità del framework;
- sia facilmente revisionabile.

Ogni contributo deve rispettare integralmente quanto definito nella documentazione ufficiale del progetto.

---

# 2. Documentazione di Riferimento

Prima di contribuire è obbligatorio conoscere la seguente documentazione.

Ordine di priorità:

1. Software Architecture Specification (SAS)
2. Implementation Roadmap
3. Coding Standards
4. Git Workflow
5. Development Environment

---

# 3. Principi

Ogni contributo deve rispettare i principi fondamentali del framework.

- Domain-Driven Design
- Clean Architecture
- SOLID
- Composition over Inheritance
- Dependency Inversion
- Determinismo
- Immutabilità
- Testabilità

---

# 4. Processo di Sviluppo

Ogni attività deve seguire il seguente flusso.

```
Roadmap

↓

Implementazione

↓

Test

↓

Pre-Commit

↓

Commit

↓

Push

↓

Continuous Integration
```

Non è consentito modificare componenti appartenenti a Sprint futuri.

---

# 5. Prima di Scrivere Codice

Prima di iniziare qualsiasi implementazione verificare:

- la fase della Roadmap;
- le dipendenze dello Sprint;
- la Software Architecture Specification.

Se una modifica richiede una variazione architetturale:

- interrompere l'implementazione;
- documentare la motivazione;
- attendere approvazione.

---

# 6. Qualità del Codice

Ogni nuovo file deve rispettare i Coding Standards.

In particolare:

- typing completo;
- docstring;
- responsabilità singola;
- assenza di duplicazione;
- nessun codice morto;
- nessun TODO.

---

# 7. Test

Ogni nuova funzionalità deve essere accompagnata da test unitari.

Ogni test deve verificare un solo comportamento.

La copertura del progetto non deve diminuire.

---

# 8. Commit

Ogni commit deve essere:

- atomico;
- descrittivo;
- coerente con una singola modifica logica.

Formato ufficiale:

```
<ambito>: <azione>
```

Esempi.

```
shared: implementa identifier
analysis: implementa validator
repository: aggiorna readme
tests: aggiunge test identifier
```

---

# 9. Continuous Integration

Ogni modifica deve superare:

- Ruff
- MyPy
- Pytest
- Coverage

Non sono consentiti merge con pipeline fallita.

---

# 10. Pull Request

Ogni Pull Request deve:

- avere uno scopo chiaro;
- modificare una sola funzionalità;
- rispettare la Roadmap;
- rispettare la SAS.

---

# 11. Documentazione

Ogni modifica significativa deve aggiornare la documentazione corrispondente.

La documentazione è parte integrante del framework.

---

# 12. Modifiche Architetturali

Non è consentito:

- modificare la SAS;
- modificare la struttura della repository;
- introdurre nuovi package;
- introdurre nuove dipendenze;
- modificare responsabilità dei layer.

Qualunque modifica architetturale richiede una nuova RFC.

---

# 13. Regole Fondamentali

Le seguenti regole sono considerate invarianti del progetto.

1. La Software Architecture Specification è la fonte autorevole dell'architettura.

2. La Roadmap è la fonte autorevole dello sviluppo.

3. I Coding Standards sono la fonte autorevole dello stile del codice.

4. Nessun contributo può violare uno dei documenti ufficiali.

5. Ogni modifica deve mantenere il framework deterministico.

6. Ogni nuova funzionalità deve essere testabile.

7. Ogni contributo deve migliorare la qualità complessiva del progetto.

---

# 14. Stato della Specifica

Questo documento definisce il processo ufficiale di contribuzione al framework SMAVS.

Ogni contributo futuro dovrà rispettare integralmente le regole qui descritte.