From 3bf84e41637bdcff0033e9ae784e5f99eda905a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Niccol=C3=B2=20Passera?= Date: Thu, 6 Aug 2026 15:45:11 +0200 Subject: [PATCH] repository: aggiunta di documentazione base --- docs/development/coding-standards.md | 514 +++++++++++++++++++++++++++ docs/development/contributing.md | 225 ++++++++++++ docs/development/dev-environment.md | 398 +++++++++++++++++++++ docs/development/git-workflow.md | 380 ++++++++++++++++++++ 4 files changed, 1517 insertions(+) create mode 100644 docs/development/coding-standards.md create mode 100644 docs/development/contributing.md create mode 100644 docs/development/dev-environment.md create mode 100644 docs/development/git-workflow.md diff --git a/docs/development/coding-standards.md b/docs/development/coding-standards.md new file mode 100644 index 0000000..2578521 --- /dev/null +++ b/docs/development/coding-standards.md @@ -0,0 +1,514 @@ +# SMAVS Coding Standards + +**Version:** 1.0.0 +**Status:** Approved +**Project:** Spiral – SMAVS Composition Engine + +--- + +# 1. Scopo + +Questo documento definisce gli standard ufficiali di sviluppo del framework **SMAVS (Su Misura Al Vostro Sistema)**. + +Ogni file del progetto deve rispettare le regole qui descritte. + +L'obiettivo è garantire: + +- uniformità del codice; +- elevata leggibilità; +- semplicità di manutenzione; +- coerenza architetturale; +- qualità costante durante l'intero ciclo di vita del framework. + +Le presenti regole costituiscono lo standard ufficiale di sviluppo del progetto. + +--- + +# 2. Principi Fondamentali + +Il codice deve sempre rispettare i seguenti principi. + +## Leggibilità + +Il codice viene letto molte più volte di quante venga scritto. + +La leggibilità ha sempre priorità rispetto alla brevità. + +--- + +## Esplicitezza + +L'esplicito è sempre preferibile all'implicito. + +Il comportamento del codice deve risultare evidente senza richiedere interpretazioni. + +--- + +## Determinismo + +Ogni componente deve produrre sempre lo stesso risultato a parità di input. + +--- + +## Immutabilità + +I modelli del dominio sono immutabili. + +--- + +## Single Responsibility + +Ogni classe possiede una singola responsabilità. + +--- + +## Composition over Inheritance + +La composizione è sempre preferibile all'ereditarietà. + +--- + +## Dependency Inversion + +Le dipendenze devono sempre puntare verso le astrazioni. + +--- + +## Testabilità + +Ogni componente deve poter essere testato in isolamento. + +--- + +# 3. Convenzioni Generali + +## Versione Python + +Python 3.11+ + +--- + +## Formatter + +Ruff Format + +--- + +## Linter + +Ruff + +--- + +## Type Checker + +MyPy + +--- + +## Testing + +Pytest + +--- + +## Coverage + +Coverage minimo: + +95% + +--- + +# 4. Convenzioni di Naming + +## Package + +snake_case + +``` +shared +value_objects +analysis +composition +``` + +--- + +## Moduli + +snake_case + +``` +identifier.py +module_registry.py +composition_context.py +``` + +--- + +## Classi + +PascalCase + +``` +Identifier +CompositionContext +ModuleRegistry +``` + +--- + +## Funzioni + +snake_case + +``` +build_context() +resolve_modules() +``` + +--- + +## Variabili + +snake_case + +``` +execution_plan +module_registry +``` + +--- + +## Costanti + +UPPER_CASE + +``` +DEFAULT_PRIORITY +MAX_DEPTH +``` + +--- + +## Membri privati + +Singolo underscore + +``` +_identifier +_registry +``` + +--- + +# 5. Organizzazione della Repository + +Ogni package deve contenere esclusivamente componenti appartenenti alla propria responsabilità. + +Non sono consentite dipendenze circolari. + +--- + +# 6. Organizzazione dei File + +Ogni file Python deve seguire rigorosamente il seguente ordine. + +``` +Module Docstring + +↓ + +Future Imports + +↓ + +Standard Library + +↓ + +Third Party Imports + +↓ + +Project Imports + +↓ + +__all__ + +↓ + +Constants + +↓ + +Classi + +↓ + +Funzioni +``` + +--- + +# 7. Organizzazione degli Import + +Gli import devono essere ordinati nel seguente modo. + +```python +from __future__ import annotations + +from dataclasses import dataclass + +from pathlib import Path + +from typing import Final + +from smavs.shared... +``` + +Non sono consentiti import inutilizzati. + +Non sono consentiti wildcard import. + +``` +from package import * +``` + +--- + +# 8. Docstring + +Ogni modulo pubblico deve possedere una docstring. + +Ogni classe pubblica deve possedere una docstring. + +Ogni metodo pubblico deve possedere una docstring quando il comportamento non è immediatamente evidente. + +Lo stile adottato è **Google Style**. + +--- + +# 9. Type Hinting + +Tutte le funzioni devono utilizzare typing completo. + +Consentito + +```python +def build(name: str) -> Identifier: +``` + +Non consentito + +```python +def build(name): +``` + +--- + +Mai utilizzare + +``` +list +dict +tuple +set +``` + +Utilizzare sempre + +``` +list[str] +dict[str, str] +tuple[int, ...] +set[str] +``` + +--- + +# 10. Dataclass + +Tutti i Value Object devono essere dichiarati nel seguente modo. + +```python +@dataclass( + frozen=True, + slots=True, +) +``` + +Le dataclass mutabili non sono consentite nel dominio. + +--- + +# 11. Protocol + +Le interfacce del Core devono essere implementate tramite Protocol. + +Non utilizzare classi astratte salvo casi eccezionali. + +--- + +# 12. Value Object + +I Value Object devono: + +- essere immutabili; +- essere hashable; +- essere confrontabili; +- non possedere identità. + +--- + +# 13. Entity + +Le Entity devono: + +- possedere un Identifier; +- mantenere la propria identità; +- incapsulare il proprio stato. + +--- + +# 14. Aggregate Root + +Ogni Aggregate Root è responsabile della consistenza del proprio Aggregate. + +Le modifiche interne devono essere sempre controllate dall'Aggregate Root. + +--- + +# 15. Domain Events + +I Domain Event rappresentano fatti già accaduti. + +Sono immutabili. + +--- + +# 16. Exceptions + +È vietato utilizzare + +```python +raise Exception(...) +``` + +Ogni errore deve derivare da: + +``` +SMAVSError +``` + +--- + +# 17. Logging + +Utilizzare esclusivamente logging strutturato. + +Non utilizzare print(). + +--- + +# 18. Testing + +Ogni componente deve possedere test unitari. + +La struttura deve seguire il pattern: + +``` +Arrange + +Act + +Assert +``` + +--- + +Ogni test deve verificare un solo comportamento. + +--- + +# 19. Commenti + +I commenti devono spiegare il perché. + +Mai spiegare il cosa. + +--- + +# 20. Refactoring + +Prima di effettuare un refactoring verificare: + +- retrocompatibilità; +- copertura dei test; +- conformità alla SAS. + +--- + +# 21. Checklist prima del Commit + +Verificare sempre: + +- Ruff +- MyPy +- Pytest +- Coverage +- Pre-Commit + +Tutti i controlli devono risultare verdi. + +--- + +# 22. Checklist prima della Pull Request + +La Pull Request deve: + +- compilare correttamente; +- superare la CI; +- mantenere il coverage; +- rispettare la SAS; +- rispettare la Roadmap. + +--- + +# 23. Regole Fondamentali + +Le seguenti regole sono considerate invarianti del progetto. + +1. Il codice deve essere leggibile prima di essere intelligente. + +2. L'esplicito è preferibile all'implicito. + +3. Ogni classe possiede una sola responsabilità. + +4. Il dominio non conosce l'infrastruttura. + +5. Nessuna dipendenza circolare. + +6. Nessun TODO nel codice. + +7. Nessun codice morto. + +8. Nessun wildcard import. + +9. Nessuna eccezione generica. + +10. Ogni nuova funzionalità deve essere testabile. + +11. Ogni modifica deve rispettare la Software Architecture Specification. + +12. Ogni implementazione deve seguire rigorosamente l'Implementation Roadmap. + +--- + +# 24. Stato della Specifica + +Questo documento costituisce lo standard ufficiale di sviluppo del framework SMAVS. + +Ogni nuovo contributo al progetto deve rispettare integralmente le regole qui definite. diff --git a/docs/development/contributing.md b/docs/development/contributing.md new file mode 100644 index 0000000..f9b96b9 --- /dev/null +++ b/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: + +``` +: +``` + +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. diff --git a/docs/development/dev-environment.md b/docs/development/dev-environment.md new file mode 100644 index 0000000..085168f --- /dev/null +++ b/docs/development/dev-environment.md @@ -0,0 +1,398 @@ +# SMAVS Development Environment + +**Version:** 1.0.0 +**Status:** Approved +**Project:** Spiral – SMAVS Composition Engine + +--- + +# 1. Scopo + +Questo documento definisce l'ambiente di sviluppo ufficiale del framework **SMAVS (Su Misura Al Vostro Sistema)**. + +L'obiettivo è garantire che tutti gli sviluppatori utilizzino un ambiente coerente, riproducibile e conforme agli standard del progetto. + +--- + +# 2. Requisiti di Sistema + +## Sistema Operativo + +Sistemi supportati: + +- Windows 11 +- Linux +- macOS + +--- + +## Python + +Versione minima supportata + +``` +Python 3.11 +``` + +Versioni consigliate + +``` +Python 3.11.x +Python 3.12.x +``` + +--- + +## Git + +Versione minima + +``` +Git 2.40+ +``` + +--- + +# 3. Repository + +Clonare il repository ufficiale. + +```bash +git clone https://gitea.netbird.smavs.duckdns.org/SMAVS/smavs.git +``` + +Entrare nella directory. + +```bash +cd smavs +``` + +--- + +# 4. Ambiente Virtuale + +Ogni sviluppo deve essere effettuato all'interno di un ambiente virtuale dedicato. + +Creazione + +```bash +python -m venv .venv +``` + +--- + +## Windows + +```powershell +.\.venv\Scripts\Activate.ps1 +``` + +--- + +## Linux + +```bash +source .venv/bin/activate +``` + +--- + +## macOS + +```bash +source .venv/bin/activate +``` + +--- + +# 5. Installazione Dipendenze + +Installazione del progetto in modalità editable. + +```bash +python -m pip install -e ".[dev]" +``` + +Le dipendenze di sviluppo comprendono: + +- Ruff +- MyPy +- Pytest +- Coverage +- MkDocs +- MkDocs Material +- Pre-Commit + +--- + +# 6. Configurazione Git + +Configurare il proprio utente Git. + +```bash +git config --global user.name "" +git config --global user.email "" +``` + +Impostare il branch predefinito. + +```bash +git config --global init.defaultBranch main +``` + +--- + +# 7. Pre-Commit + +Installazione degli hook. + +```bash +python -m pre_commit install +``` + +Verifica manuale. + +```bash +python -m pre_commit run --all-files +``` + +Tutti gli hook devono risultare verdi prima di ogni commit. + +--- + +# 8. Ruff + +Verifica del codice. + +```bash +python -m ruff check . +``` + +Correzione automatica. + +```bash +python -m ruff check . --fix +``` + +Formatter. + +```bash +python -m ruff format . +``` + +Verifica formatter. + +```bash +python -m ruff format --check . +``` + +--- + +# 9. MyPy + +Verifica del typing. + +```bash +python -m mypy . +``` + +--- + +# 10. Pytest + +Esecuzione dei test. + +```bash +python -m pytest +``` + +--- + +# 11. Coverage + +Esecuzione della coverage. + +```bash +python -m coverage run -m pytest +python -m coverage report +``` + +Generazione del report HTML. + +```bash +python -m coverage html +``` + +--- + +# 12. MkDocs + +Avvio del server locale. + +```bash +mkdocs serve +``` + +Generazione della documentazione. + +```bash +mkdocs build +``` + +--- + +# 13. Workflow Quotidiano + +Ogni attività di sviluppo deve seguire il seguente flusso. + +``` +git pull + +↓ + +Sviluppo + +↓ + +git status + +↓ + +git add . + +↓ + +python -m pre_commit run --all-files + +↓ + +git commit + +↓ + +git push +``` + +--- + +# 14. Continuous Integration + +Ogni push attiva automaticamente la pipeline CI. + +La pipeline verifica: + +- Ruff +- MyPy +- Pytest +- Coverage + +Il branch `main` deve rimanere sempre stabile. + +--- + +# 15. Visual Studio Code + +Estensioni consigliate. + +- Python +- Pylance +- Ruff +- EditorConfig +- GitLens +- Markdown All in One + +--- + +Impostazioni consigliate. + +```json +{ + "editor.formatOnSave": true, + "editor.codeActionsOnSave": { + "source.fixAll.ruff": "explicit", + "source.organizeImports.ruff": "explicit" + }, + "files.eol": "\n", + "files.insertFinalNewline": true, + "files.trimTrailingWhitespace": true, + "python.analysis.typeCheckingMode": "strict" +} +``` + +--- + +# 16. Directory Generate Automaticamente + +Le seguenti directory non devono essere versionate. + +``` +.venv/ +__pycache__/ +.pytest_cache/ +.ruff_cache/ +.mypy_cache/ +htmlcov/ +site/ +``` + +--- + +# 17. Aggiornamento Dipendenze + +Aggiornare periodicamente le dipendenze. + +```bash +python -m pip install --upgrade pip + +python -m pip install -e ".[dev]" +``` + +--- + +# 18. Risoluzione Problemi + +Ricreare completamente l'ambiente virtuale. + +Windows + +```powershell +Remove-Item -Recurse -Force .venv +python -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install -e ".[dev]" +``` + +Linux / macOS + +```bash +rm -rf .venv +python -m venv .venv +source .venv/bin/activate +python -m pip install -e ".[dev]" +``` + +--- + +# 19. Regole Fondamentali + +1. Utilizzare sempre un ambiente virtuale dedicato. + +2. Installare sempre le dipendenze tramite il gruppo `dev`. + +3. Utilizzare sempre `python -m` per eseguire gli strumenti. + +4. Eseguire sempre `pre-commit` prima di ogni commit. + +5. Non effettuare push con hook non superati. + +6. Non modificare manualmente la configurazione degli strumenti senza approvazione. + +7. Mantenere sincronizzato l'ambiente locale con il repository. + +--- + +# 20. Stato della Specifica + +Questo documento costituisce la specifica ufficiale dell'ambiente di sviluppo del framework SMAVS. + +Ogni ambiente di sviluppo deve essere configurato secondo le regole qui definite. diff --git a/docs/development/git-workflow.md b/docs/development/git-workflow.md new file mode 100644 index 0000000..8bc7f09 --- /dev/null +++ b/docs/development/git-workflow.md @@ -0,0 +1,380 @@ +# 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 ": " +``` + +Pubblicare le modifiche: + +```bash +git push origin main +``` + +--- + +# 5. Convenzione dei Commit + +Ogni commit deve seguire il formato: + +``` +: +``` + +--- + +## 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.