Contributing.fr

Contribuer au projet

Merci de vouloir contribuer à WorkPilot AI ! Ce guide résume le processus — la source de référence reste CONTRIBUTING.md dans le dépôt.

---

🧭 Vue d'ensemble

1. Fork le dépôt
2. Créez une branche depuis develop (pas main)
3. Implémentez vos changements
4. Lancez tests, lint et typecheck
5. Ouvrez une Pull Request ciblant develop
6. Attendez la revue CI + humaine
7. Après approbation, merge

---

📋 Règles critiques

Avant de toucher au code, gardez ces règles en tête (extraites de CLAUDE.md) :

• Claude Agent SDK uniquement — ne jamais utiliser anthropic.Anthropic() directement. Toujours create_client() de core.client
• i18n obligatoire — toute chaîne d'UI doit utiliser react-i18next et être traduite en français ET en anglais
• Abstraction cross-plateforme — jamais process.platform directement. Utilisez les modules platform/
• Pas d'estimations temporelles — utilisez la priorité, pas l'estimation en heures
• PRs vers develop — la branche cible par défaut est develop, pas main

---

🛠 Setup environnement de dev

Prérequis

• Python 3.12+ avec uv
• Node.js 20+ (24 recommandé) avec pnpm 8+
• Git

Installation

# Cloner votre fork
git clone https://github.com/<votre-user>/WorkPilot-AI.git
cd WorkPilot-AI

# Ajouter le remote upstream
git remote add upstream https://github.com/krovomi/WorkPilot-AI.git

# Installer toutes les dépendances
pnpm run install:all

# Ou séparément
cd apps/backend && uv venv && uv pip install -r requirements.txt
cd ../frontend && pnpm install

Lancer en dev

# À la racine
pnpm run dev

---

📝 Workflow Git

Créer une branche

git checkout develop
git pull upstream develop
git checkout -b feat/ma-fonctionnalite

Convention de nommage des branches

• feat/<nom> — nouvelle fonctionnalité
• fix/<nom> — correction de bug
• docs/<nom> — doc uniquement
• refactor/<nom> — refactoring sans changement fonctionnel
• test/<nom> — ajout ou amélioration de tests
• chore/<nom> — tooling, dépendances, CI

Messages de commit (Conventional Commits)

<type>(<scope>): <description courte>

<description longue optionnelle>

Exemples :

feat(kanban): add automatic column transitions
fix(auth): resolve OAuth token refresh race condition
docs(wiki): add French translation for Installation page
refactor(agent-queue): extract priority logic to dedicated module
test(qa-fixer): add coverage for 50-iteration limit

---

✅ Checks avant PR

Frontend

cd apps/frontend
pnpm run lint          # Biome check
pnpm run lint:fix      # Biome auto-fix
pnpm run typecheck     # TypeScript strict
pnpm test              # Vitest
pnpm test:e2e          # Playwright (optionnel)

Backend

cd apps/backend
.venv/bin/pytest tests/ -v     # Tous les tests
ruff check .                    # Linting
ruff format .                   # Auto-format

Tout d'un coup

# Depuis la racine
pnpm run test:backend
pnpm run test:frontend

Hooks pre-commit

Husky + lint-staged lancent automatiquement Biome sur les fichiers .ts/.tsx/.js/.jsx/.json stagés au commit. Si ça échoue, corrigez et recommencez.

---

🌐 i18n

Toute chaîne UI doit passer par react-i18next :

// ❌ INTERDIT
<span>Tasks</span>

// ✅ OBLIGATOIRE
<span>{t('navigation:items.tasks')}</span>

Ajouter une clé

1. Ajoutez dans apps/frontend/src/shared/i18n/locales/en/<namespace>.json
2. Ajoutez la traduction française dans apps/frontend/src/shared/i18n/locales/fr/<namespace>.json
3. Utilisez namespace:section.key dans le JSX

55 namespaces existent (common, navigation, settings, tasks, kanban, github, insights, etc.). Choisissez le namespace le plus pertinent ou créez-en un nouveau.

---

🧪 Écrire des tests

Frontend — Vitest + React Testing Library

// apps/frontend/src/renderer/components/__tests__/MyComponent.test.tsx
import { render, screen } from '@testing-library/react';
import { MyComponent } from '../MyComponent';

describe('MyComponent', () => {
  it('should render the title', () => {
    render(<MyComponent title="Hello" />);
    expect(screen.getByText('Hello')).toBeInTheDocument();
  });
});

Backend — pytest

# tests/test_my_feature.py
import pytest
from agents.my_feature import do_something

def test_do_something_returns_expected():
    result = do_something(input_value=42)
    assert result == 84

@pytest.mark.asyncio
async def test_async_behavior():
    result = await async_function()
    assert result.status == "ok"

---

🔀 Ouvrir une Pull Request

Checklist PR

• Branche créée depuis develop
• Tests ajoutés ou mis à jour
• pnpm run lint passe
• pnpm run typecheck passe
• pnpm test passe
• i18n : clés ajoutées en EN et FR
• Documentation mise à jour si API publique modifiée
• Message de commit au format Conventional Commits
• PR cible develop (pas main)

Format du titre

Comme les commits :

feat(scope): description courte sous 70 chars

Description

Utilisez le template de PR :

• Summary — 1 à 3 bullets sur ce qui change
• Test plan — comment vous avez validé
• Screenshots si changement UI
• Breaking changes s'il y en a

---

🧹 Qualité de code

Frontend

• Biome pour lint + format
• TypeScript strict activé
• Pas de any sauf exception justifiée en commentaire
• Pas de commentaires redondants — le code doit se suffire

Backend

• Ruff pour lint + format
• Type hints systématiques (annotations Python)
• Docstrings sur fonctions publiques
• pytest.mark.asyncio pour les tests async

---

🧷 Où trouver quoi ?

Besoin	Emplacement
Ajouter un prompt d'agent	apps/backend/prompts/<nom>.md
Créer un Zustand store	apps/frontend/src/renderer/stores/<nom>-store.ts
Créer un IPC handler	apps/frontend/src/main/ipc-handlers/<domaine>.ts
Ajouter une traduction	apps/frontend/src/shared/i18n/locales/{en,fr}/
Ajouter un thème	apps/frontend/src/shared/constants/themes.ts
Ajouter un runner CLI	apps/backend/runners/
Ajouter une intégration	apps/backend/integrations/<nom>/

---

🆘 Besoin d'aide ?

• Discord : rejoindre la communauté
• Discussions GitHub : https://github.com/krovomi/WorkPilot-AI/discussions
• Issues : https://github.com/krovomi/WorkPilot-AI/issues

---

📜 Licence

En contribuant, vous acceptez que vos contributions soient licenciées sous AGPL-3.0, la licence du projet.

---

Prochaine étape

➡️ Dépannage