decision/docs/content/dev/7.contributing.md

title, description

title	description
Contribution	Guide de contribution au projet libreDecision

Guide de contribution

Merci de votre interet pour contribuer a libreDecision. Ce guide explique comment configurer l'environnement de developpement, les conventions a respecter et le processus de contribution.

Prerequis

• Python 3.11+
• Node.js 20+
• PostgreSQL 16
• Docker et Docker Compose (optionnel mais recommande)
• Git

Installation locale

Methode 1 : Docker (recommandee)

# Cloner le depot
git clone https://git.duniter.org/tools/libredecision.git
cd libredecision

# Copier le fichier d'environnement
cp .env.example .env

# Demarrer tous les services
docker compose -f docker/docker-compose.yml -f docker/docker-compose.dev.yml up

Les services sont accessibles sur :

• Frontend : http://localhost:3002
• Backend : http://localhost:8002
• API docs : http://localhost:8002/docs

Methode 2 : Installation manuelle

# Backend
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --port 8002 --reload

# Frontend (dans un autre terminal)
cd frontend
npm install
npm run dev

Assurez-vous qu'une instance PostgreSQL est disponible et que DATABASE_URL dans .env pointe vers celle-ci.

Conventions

Langues

• Code (variables, commentaires, docstrings) : anglais
• Interface utilisateur (labels, messages, documentation) : francais

Structure du code

Le backend est organise par domaine :

backend/app/
  models/       # Modeles SQLAlchemy (un fichier par domaine)
  schemas/      # Schemas Pydantic v2 (un fichier par domaine)
  routers/      # Routes FastAPI (un fichier par domaine)
  services/     # Logique metier (un fichier par domaine)
  engine/       # Moteur de calcul (formules, seuils)
  tests/        # Tests unitaires

Le frontend suit les conventions Nuxt 4 :

frontend/app/
  components/   # Composants Vue (un dossier par domaine)
  composables/  # Composables reutilisables
  pages/        # Pages (un dossier par domaine)
  stores/       # Stores Pinia
  utils/        # Utilitaires

Style de code

• Python : PEP 8, type hints systematiques, docstrings au format NumPy
• TypeScript/Vue : ESLint + Prettier (via configuration Nuxt)
• SQL : noms de tables au pluriel, noms de colonnes en snake_case

API

• Versionne sous /api/v1/
• Schemas Pydantic v2 pour la validation
• Async partout (SQLAlchemy AsyncSession, FastAPI async handlers)
• Codes HTTP standards (201 pour creation, 204 pour suppression, 404, 409, etc.)

Tests

Backend

cd backend
pytest app/tests/ -v

Les tests du moteur de calcul (test_threshold.py) verifient la formule de seuil WoT avec le cas de reference (Engagement Forgeron v2.0.0 : 97/23 avec WoT 7224).

Frontend

cd frontend
npm run build  # Verification que le build passe

Processus de contribution

1. Creer une branche a partir de main : git checkout -b feature/ma-fonctionnalite
2. Developper et tester localement
3. S'assurer que les tests passent : pytest (backend) et npm run build (frontend)
4. Pousser la branche et creer une merge request
5. La pipeline CI (Woodpecker) validera automatiquement les tests
6. Revue de code par un mainteneur
7. Merge dans main

Secrets Woodpecker CI

La pipeline CI utilise les secrets suivants (a configurer dans l'interface Woodpecker) :

Secret	Description
docker_registry	URL du registre Docker
docker_username	Nom d'utilisateur du registre
docker_password	Mot de passe du registre
deploy_host	Adresse du serveur de deploiement
deploy_username	Utilisateur SSH du serveur
deploy_key	Cle privee SSH pour le deploiement

Contact

Pour toute question, rendez-vous sur le forum Duniter ou ouvrez une issue sur le depot Git.