repository: aggiunta di documentazione base

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 "<Nome>"
+git config --global user.email "<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.