senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/veza-docs/vision/domains/backend/contributing.md

7.6 KiB
Raw Blame History

id title sidebar_label
contributing 🤝 Guide de Contribution - Veza Platform 🤝 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

# 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

# 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

# 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

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