3.8 KiB
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à:
- Software Architecture Specification (SAS)
- Implementation Roadmap
- Coding Standards
- Git Workflow
- 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.
-
La Software Architecture Specification è la fonte autorevole dell'architettura.
-
La Roadmap è la fonte autorevole dello sviluppo.
-
I Coding Standards sono la fonte autorevole dello stile del codice.
-
Nessun contributo può violare uno dei documenti ufficiali.
-
Ogni modifica deve mantenere il framework deterministico.
-
Ogni nuova funzionalità deve essere testabile.
-
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.