repository: aggiunta di documentazione base

docs/development/contributing.md

@@ -0,0 +1,225 @@
+# 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.