399 lines
4.8 KiB
Markdown
399 lines
4.8 KiB
Markdown
# 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.
|