226 lines
3.8 KiB
Markdown
226 lines
3.8 KiB
Markdown
# 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.
|