281 lines
7.6 KiB
Markdown
281 lines
7.6 KiB
Markdown
---
|
|
id: "contributing"
|
|
title: "🤝 Guide de Contribution - Veza Platform"
|
|
sidebar_label: "🤝 Guide de Contribution - Veza Platform"
|
|
---
|
|
> NOTE: Cette page décrit la CIBLE (but visé).
|
|
|
|
# 🤝 Guide de Contribution - Veza Platform
|
|
|
|
> **Guide complet pour contribuer au projet Veza Platform avec environnement de développement assisté par IA**
|
|
|
|
## 🎯 Principes de Conduite (Non Négociables)
|
|
|
|
### Stabilité avant Vélocité
|
|
- Chaque changement améliore la robustesse (tests, types, lint, docs)
|
|
- Aucun raccourci qui compromet la qualité
|
|
- Tests obligatoires pour toute nouvelle fonctionnalité
|
|
|
|
### Flux Unidirectionnel
|
|
```
|
|
Besoin → Design → Implémentation → Test → Doc → PR → Review → Merge
|
|
```
|
|
**Pas de raccourcis autorisés**
|
|
|
|
### Traçabilité Totale
|
|
- Toute décision = **ADR** (Architecture Decision Record)
|
|
- Commits atomiques avec **Conventional Commits**
|
|
- Documentation à jour pour chaque changement
|
|
|
|
### Sécurité Intégrée
|
|
- Aucune fuite de secrets
|
|
- Scanners de secrets obligatoires
|
|
- Dépendances vérifiées automatiquement
|
|
|
|
### Autonomie Contrôlée
|
|
- Agents IA travaillent en arrière-plan
|
|
- **Toujours via PR** + checklists
|
|
- Review humaine obligatoire
|
|
|
|
## 🚀 Démarrage Rapide
|
|
|
|
### 1. Configuration Initiale
|
|
```bash
|
|
# Cloner le repository
|
|
git clone https://github.com/okinrev/veza-full-stack.git
|
|
cd veza-full-stack
|
|
|
|
# Installer les dépendances et hooks
|
|
make bootstrap
|
|
|
|
# Vérifier l'installation
|
|
make verify
|
|
```
|
|
|
|
### 2. Workflow de Développement
|
|
```bash
|
|
# 1. Créer une branche feature
|
|
git checkout -b feat/your-feature-name
|
|
|
|
# 2. Développer avec les agents IA
|
|
# Les agents Implementer, QA, Docs travaillent automatiquement
|
|
|
|
# 3. Vérifier avant commit
|
|
make verify && make test
|
|
|
|
# 4. Créer une PR
|
|
# Template automatiquement rempli avec checklist DOD
|
|
```
|
|
|
|
## 📋 Definition of Done (DOD)
|
|
|
|
### ✅ Code Quality
|
|
- [ ] **Compilation** : Code compile sans erreurs
|
|
- [ ] **Linting** : Lint passé (ESLint, golangci-lint, clippy)
|
|
- [ ] **Type Checking** : Types stricts (TS/Go/Rust)
|
|
- [ ] **Tests** : Couverture ≥ 80% sur packages critiques
|
|
- [ ] **Performance** : Benchmarks respectés si impact
|
|
|
|
### ✅ Tests Obligatoires
|
|
- [ ] **Tests unitaires** : Nouveaux tests pour nouvelle logique
|
|
- [ ] **Tests d'intégration** : Au moins 1 test si nouvelle route/service
|
|
- [ ] **Tests E2E** : Si impact frontend/API
|
|
- [ ] **Tests de régression** : Si correction de bug
|
|
|
|
### ✅ Documentation
|
|
- [ ] **Vision/Current** : Docs mises à jour selon impact
|
|
- [ ] **README** : Mise à jour si changement d'usage
|
|
- [ ] **Changelog** : Entrée ajoutée
|
|
- [ ] **Exemples** : Code d'usage fourni
|
|
|
|
### ✅ Sécurité
|
|
- [ ] **Secrets** : Aucune fuite détectée (gitleaks)
|
|
- [ ] **Dépendances** : Vulnérabilités corrigées
|
|
- [ ] **Permissions** : Droits minimaux respectés
|
|
- [ ] **Validation** : Inputs validés et sanitizés
|
|
|
|
### ✅ Architecture
|
|
- [ ] **ADR** : Décision documentée si impact architectural
|
|
- [ ] **API** : Contrats versionnés et documentés
|
|
- [ ] **Logs** : Logging structuré avec corrélation
|
|
- [ ] **Observabilité** : Métriques ajoutées si nécessaire
|
|
|
|
### ✅ Review Process
|
|
- [ ] **2 Approbations** : Tech + QA minimum
|
|
- [ ] **Auto-fusion** : Interdite
|
|
- [ ] **Checklist** : Tous les items cochés
|
|
- [ ] **Conflits** : Résolus avant merge
|
|
|
|
## 🔄 Workflow Git
|
|
|
|
### Branches
|
|
- `main` : Production stable
|
|
- `develop` : Intégration continue
|
|
- `feat/*` : Nouvelles fonctionnalités
|
|
- `fix/*` : Corrections de bugs
|
|
- `refactor/*` : Refactoring
|
|
- `docs/*` : Documentation
|
|
- `chore/*` : Maintenance
|
|
|
|
### Conventional Commits
|
|
```bash
|
|
# Format
|
|
<type>(<scope>): <description>
|
|
|
|
# Types
|
|
feat: Nouvelle fonctionnalité
|
|
fix: Correction de bug
|
|
docs: Documentation
|
|
style: Formatage
|
|
refactor: Refactoring
|
|
test: Tests
|
|
chore: Maintenance
|
|
|
|
# Exemples
|
|
feat(auth): add OAuth2 Google provider
|
|
fix(chat): resolve WebSocket connection issues
|
|
docs(api): update authentication endpoints
|
|
refactor(backend): improve error handling
|
|
```
|
|
|
|
### Pull Request Process
|
|
1. **Créer branche** depuis `develop`
|
|
2. **Développer** avec agents IA
|
|
3. **Tester** localement (`make test`)
|
|
4. **Créer PR** avec template
|
|
5. **Review** par 2+ personnes
|
|
6. **Merge** après approbation
|
|
|
|
## 🤖 Agents IA
|
|
|
|
### 6 Agents en Arrière-Plan
|
|
|
|
#### 1. **Planner** (Planificateur)
|
|
- **Rôle** : Priorisation et planification
|
|
- **Entrées** : Vision, roadmap, issues
|
|
- **Sorties** : Backlog priorisé, jalons
|
|
- **Boucle** : Quotidienne
|
|
|
|
#### 2. **Researcher** (Chercheur)
|
|
- **Rôle** : Recherche et analyse
|
|
- **Entrées** : Tâches bloquées
|
|
- **Sorties** : Notes de recherche, options
|
|
- **Boucle** : Ad-hoc
|
|
|
|
#### 3. **Implementer** (Implémenteur)
|
|
- **Rôle** : Développement de code
|
|
- **Entrées** : Items Now/Next
|
|
- **Sorties** : Branches, code, tests
|
|
- **Boucle** : Continue
|
|
|
|
#### 4. **QA** (Qualité)
|
|
- **Rôle** : Tests et validation
|
|
- **Entrées** : PR ouvertes
|
|
- **Sorties** : Rapports de qualité
|
|
- **Boucle** : À chaque PR
|
|
|
|
#### 5. **Docs** (Documentation)
|
|
- **Rôle** : Mise à jour documentation
|
|
- **Entrées** : PR prêtes
|
|
- **Sorties** : Docs Vision/Current
|
|
- **Boucle** : À chaque PR
|
|
|
|
#### 6. **Maintainer** (Maintenance)
|
|
- **Rôle** : Maintenance et sécurité
|
|
- **Entrées** : Dépendances, vulnérabilités
|
|
- **Sorties** : PR de maintenance
|
|
- **Boucle** : Hebdomadaire
|
|
|
|
## 🛠️ Outillage Local
|
|
|
|
### Makefile Commands
|
|
```bash
|
|
make bootstrap # Installation complète
|
|
make verify # Lint + typecheck + secrets
|
|
make test # Tests unitaires + intégration
|
|
make docs # Build documentation
|
|
make diagrams # Génération diagrammes Mermaid
|
|
make clean # Nettoyage artefacts
|
|
```
|
|
|
|
### Pre-commit Hooks
|
|
- **Go** : `golangci-lint`, `go vet`
|
|
- **Rust** : `cargo clippy`, `cargo fmt`
|
|
- **TypeScript** : `eslint`, `tsc --noEmit`
|
|
- **Markdown** : `markdownlint`
|
|
- **Secrets** : `gitleaks`
|
|
|
|
### Configuration IDE
|
|
- **VSCode** : Extensions recommandées dans `.vscode/`
|
|
- **Settings** : Configuration partagée
|
|
- **Debug** : Configurations de debug
|
|
|
|
## 📊 Métriques et Qualité
|
|
|
|
### Couverture de Code
|
|
- **Backend Go** : ≥ 80%
|
|
- **Rust Services** : ≥ 85%
|
|
- **Frontend React** : ≥ 75%
|
|
- **Tests E2E** : ≥ 60%
|
|
|
|
### Performance
|
|
- **API Latency** : < 100ms P95
|
|
- **Frontend Load** : < 2s
|
|
- **Memory Usage** : < 512MB per service
|
|
- **CPU Usage** : < 50% average
|
|
|
|
### Sécurité
|
|
- **Vulnerabilities** : 0 critical, 0 high
|
|
- **Secrets** : 0 detected
|
|
- **Dependencies** : Up to date
|
|
- **Licenses** : Compatible
|
|
|
|
## 🚨 Gestion des Incidents
|
|
|
|
### Classification
|
|
- **P0** : Service down, data loss
|
|
- **P1** : Major feature broken
|
|
- **P2** : Minor feature broken
|
|
- **P3** : Enhancement request
|
|
|
|
### Processus
|
|
1. **Détection** : Monitoring automatique
|
|
2. **Alerte** : Notification équipe
|
|
3. **Diagnostic** : Analyse logs/métriques
|
|
4. **Correction** : Hotfix si P0/P1
|
|
5. **Post-mortem** : Analyse et prévention
|
|
|
|
## 📚 Ressources
|
|
|
|
### Documentation
|
|
- **Vision** : `/vision/overview`
|
|
- **État actuel** : `/current/overview`
|
|
- **API** : `/current/tech/api-reference`
|
|
- **Architecture** : `/current/tech/architecture`
|
|
|
|
### Communication
|
|
- **Issues** : GitHub Issues
|
|
- **Discussions** : GitHub Discussions
|
|
- **Code Review** : GitHub PR
|
|
- **Urgent** : Slack/Teams
|
|
|
|
### Formation
|
|
- **Onboarding** : Guide complet
|
|
- **Best Practices** : Exemples concrets
|
|
- **Troubleshooting** : Solutions communes
|
|
- **Architecture** : Principes et patterns
|
|
|
|
## 🎯 Prochaines Étapes
|
|
|
|
1. **Lire** ce guide attentivement
|
|
2. **Configurer** l'environnement local
|
|
3. **Choisir** une tâche du backlog
|
|
4. **Créer** une branche feature
|
|
5. **Développer** avec les agents IA
|
|
6. **Tester** et documenter
|
|
7. **Créer** une PR
|
|
8. **Collaborer** via review
|
|
|
|
---
|
|
|
|
*Ce guide évolue avec le projet. Dernière mise à jour : 2024-01-15*
|