smavs/docs/development/dev-environment.md

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.

git clone https://gitea.netbird.smavs.duckdns.org/SMAVS/smavs.git

Entrare nella directory.

cd smavs

---

4. Ambiente Virtuale

Ogni sviluppo deve essere effettuato all'interno di un ambiente virtuale dedicato.

Creazione

python -m venv .venv

---

Windows

.\.venv\Scripts\Activate.ps1

---

Linux

source .venv/bin/activate

---

macOS

source .venv/bin/activate

---

5. Installazione Dipendenze

Installazione del progetto in modalità editable.

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.

git config --global user.name "<Nome>"
git config --global user.email "<Email>"

Impostare il branch predefinito.

git config --global init.defaultBranch main

---

7. Pre-Commit

Installazione degli hook.

python -m pre_commit install

Verifica manuale.

python -m pre_commit run --all-files

Tutti gli hook devono risultare verdi prima di ogni commit.

---

8. Ruff

Verifica del codice.

python -m ruff check .

Correzione automatica.

python -m ruff check . --fix

Formatter.

python -m ruff format .

Verifica formatter.

python -m ruff format --check .

---

9. MyPy

Verifica del typing.

python -m mypy .

---

10. Pytest

Esecuzione dei test.

python -m pytest

---

11. Coverage

Esecuzione della coverage.

python -m coverage run -m pytest
python -m coverage report

Generazione del report HTML.

python -m coverage html

---

12. MkDocs

Avvio del server locale.

mkdocs serve

Generazione della documentazione.

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.

{
    "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.

python -m pip install --upgrade pip

python -m pip install -e ".[dev]"

---

18. Risoluzione Problemi

Ricreare completamente l'ambiente virtuale.

Windows

Remove-Item -Recurse -Force .venv
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

Linux / macOS

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.