🤝 Guide de contribution¶

Guide complet pour contribuer au projet ProbatioVault.

← Retour à l'index | ← Présentation

📋 Table des matières¶

• Workflow de contribution
• Structure du projet
• Conventions de nommage
• Standards de qualité
• Workflow CI/CD
• Documentation

🔄 Workflow de contribution¶

1. Préparer votre environnement¶

# Cloner le projet
git clone <url-du-repo>
cd ProbatioVault-app

# Installer les dépendances
npm install

# Vérifier que tout fonctionne
npm run test:ci
npm run type-check
npm run lint

2. Créer une branche¶

# Pour une fonctionnalité
git checkout -b feature/nom-de-la-fonctionnalite

# Pour un bug
git checkout -b fix/nom-du-bug

# Pour de la documentation
git checkout -b docs/nom-de-la-doc

# Pour des tests
git checkout -b test/nom-des-tests

3. Développer¶

Workflow recommandé :

1. ✅ Écrire les tests d'abord (TDD)
2. ✅ Implémenter le code
3. ✅ Vérifier la qualité
4. ✅ Documenter les changements

Commandes pendant le développement :

# Tests en mode watch
npm test -- --watch

# Type checking en continu
npm run type-check -- --watch

# Linter avec auto-fix
npm run lint:fix

4. Vérifier avant de commit¶

# Vérification complète
npm run test:ci          # Tous les tests
npm run type-check       # TypeScript
npm run lint             # ESLint

# Si tout passe, vous êtes prêt à commit

5. Commit¶

Format des messages de commit :

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

[corps optionnel]

[footer optionnel]

Types autorisés :

• feat: Nouvelle fonctionnalité
• fix: Correction de bug
• docs: Documentation seulement
• style: Formatage, point-virgules, etc.
• refactor: Refactoring (ni feat ni fix)
• test: Ajout/modification de tests
• chore: Tâches de build, dépendances, etc.

Exemples :

git commit -m "feat(vault): add document encryption with AES-256-GCM"
git commit -m "fix(crypto): correct WordArray to Uint8Array conversion (32 bytes)"
git commit -m "test(store): add regression tests for getFolderWithStats"
git commit -m "docs(architecture): document new store structure"

6. Push et Pull Request¶

# Push vers votre branche
git push origin feature/nom-de-la-fonctionnalite

# Créer une PR sur GitHub/GitLab
# - Titre descriptif
# - Description détaillée
# - Lier les issues résolues
# - Mentionner les breaking changes

📁 Structure du projet¶

Organisation des dossiers¶

ProbatioVault-app/
├── src/                          # Code source
│   ├── components/              # Composants réutilisables
│   │   ├── common/             # UI génériques (Button, Input, etc.)
│   │   ├── vault/              # Composants métier (DocumentRow, etc.)
│   │   └── security/           # Sécurité (BiometricPrompt, etc.)
│   │
│   ├── screens/                 # Écrans de l'application
│   │   ├── auth/               # Authentification
│   │   └── vault/              # Coffre-fort (CRUD dossiers/docs)
│   │
│   ├── store/                   # État global Zustand
│   │   ├── useVaultStore.ts    # Store principal (folders, documents, proofs)
│   │   └── useAuthStore.ts     # Authentification et sécurité
│   │
│   ├── services/                # Services métier
│   │   ├── crypto.ts           # Chiffrement AES-256-GCM/CBC
│   │   ├── storage.ts          # FileSystem + SecureStore
│   │   └── api.ts              # API REST backend
│   │
│   ├── hooks/                   # Hooks React customs
│   ├── utils/                   # Utilitaires (telemetry, etc.)
│   ├── types/                   # Types TypeScript
│   ├── i18n/                    # Traductions (FR/EN)
│   └── navigation/              # React Navigation
│
├── docs/                        # Documentation
│   ├── presentation/           # Overview, architecture, concepts, roadmap
│   ├── infra/                  # Stubs vers docs infra
│   ├── storage/                # Stubs stockage/WORM
│   ├── api/                    # Stubs vers docs backend API
│   ├── clients/                # Mobile/PWA/Desktop
│   ├── guides/                 # Guides dev/B2B/CLI/examples
│   ├── refs/                   # Crypto, key hierarchy, compliance
│   ├── epics/            # PD-34, etc.
│   ├── contrib/                # Contribution interne
│   ├── bugs/                   # Bugs corrigés
│   └── tests/                  # Stratégies de test
│
├── __tests__/                   # Tests Jest
│   ├── components/
│   ├── screens/
│   ├── services/
│   └── store/
│
└── coverage/                    # Rapports de couverture

Où ajouter quoi ?¶

🏷️ Conventions de nommage¶

Fichiers¶

Code¶

// ✅ Composants React : PascalCase
export default function HomeScreen() { }
export const DocumentRow = () => { }

// ✅ Hooks : camelCase avec préfixe 'use'
export function useVault() { }
export const useBiometric = () => { }

// ✅ Fonctions : camelCase
export function encryptData() { }
export const decryptFile = async () => { }

// ✅ Constantes : SCREAMING_SNAKE_CASE
export const APP_ROOT_DIR = "/vault";
export const MAX_FILE_SIZE = 10 * 1024 * 1024;

// ✅ Types/Interfaces : PascalCase
export interface Document { }
export type Folder = { }

// ✅ Variables : camelCase
const folderName = "test";
let documentCount = 0;

Git¶

# ✅ Branches : kebab-case avec préfixe
feature/document-encryption
fix/crypto-conversion-bug
docs/contributing-guide
test/vault-store-regression

# ✅ Commits : conventional commits
feat(vault): add document list pagination
fix(crypto): correct 8-byte bug in WordArray conversion
docs(architecture): add store fusion documentation
test(store): add getFolderWithStats regression tests

✅ Standards de qualité¶

TypeScript strict¶

// ✅ Toujours typer explicitement
function encryptData(data: string): Promise<Uint8Array> { }

// ✅ Pas de 'any' sauf cas exceptionnel
// ❌ const result: any = getValue();
// ✅ const result: unknown = getValue();

// ✅ Utiliser les types génériques
const documents: Document[] = [];
const folder: FolderWithStats | null = null;

// ✅ Interfaces pour les objets
interface Props {
  folderId: string;
  onDelete: (id: string) => void;
}

ESLint¶

Le projet suit les règles ESLint strictes :

// ✅ Pas de console.log en production
// Utilisez plutôt :
import { logEvent } from './utils/telemetry';

// ✅ Pas de fonctions JSX inline dans les props
// ❌ <Component renderItem={() => <View />} />
// ✅ const renderItem = useCallback(() => <View />, []);
//    <Component renderItem={renderItem} />

// ✅ Hooks stables et ordonnés
// Les hooks doivent être appelés dans le même ordre à chaque render

// ✅ Dépendances exhaustives
useEffect(() => {
  // ...
}, [dep1, dep2]); // Toutes les dépendances listées

Tests¶

Couverture minimale requise : 70% (objectif PD-96)

Règles :

• ✅ Chaque bug fixé doit avoir un test de régression
• ✅ Nouvelles fonctionnalités : tests unitaires + tests d'intégration
• ✅ Tests de composants React pour l'UI critique
• ✅ Nommer les tests clairement : it("should do X when Y")

Exemple :

describe("crypto service", () => {
  describe("encryptData", () => {
    it("should encrypt data with AES-256-GCM", async () => {
      const result = await encryptData("test");
      expect(result).toBeDefined();
      expect(result.byteLength).toBeGreaterThan(0);
    });

    it("REGRESSION TEST: should return 32 bytes for master key (not 8)", async () => {
      const key = await decryptMasterKey(password);
      expect(key.length).toBe(32); // Détecte le bug de 8 bytes
    });
  });
});

🔄 Workflow CI/CD¶

Pipeline automatique¶

À chaque push sur une branche :

# .gitlab-ci.yml ou .github/workflows/ci.yml

1. Install dependencies
   npm install

2. Type checking
   npm run type-check

3. Linting
   npm run lint

4. Tests
   npm run test:ci

5. Build (si applicable)
   npm run build

6. Coverage report
   Upload to SonarQube/Codecov

Checks obligatoires avant merge¶

• ✅ TypeScript : 0 erreur
• ✅ ESLint : 0 erreur
• ✅ Tests : 100% passent
• ✅ Coverage : Pas de régression (≥ actuel)
• ✅ Review : Au moins 1 approbation

SonarQube¶

Le projet est analysé par SonarQube 10.5 :

• Quality Gate : Doit passer
• Code Smells : Minimiser
• Security Hotspots : Résoudre
• Duplications : < 3%
• Coverage : Objectif 70%

📝 Documentation¶

Quand documenter ?¶

Structure d'un document de bug fix¶

Utilisez le template suivant :

# 🐛 Correction du bug [NOM]

**Date**: [DATE]
**Statut**: ✅ Corrigé / ⏳ En cours
**Priorité**: 🔴 Critique / 🟡 Important / 🟢 Mineur
**Impact**: [DESCRIPTION]

## 📋 Résumé
## 🔍 Symptômes
## 🔬 Analyse technique
## ✅ Correction appliquée
## 🧪 Tests de régression
## 📊 Impact
## 📝 Fichiers modifiés
## 🎯 Leçons apprises

Mise à jour de l'index¶

Après avoir ajouté un document, mettez à jour :

1. presentation/overview.md - Point d'entrée
2. README.md du dossier - Index de la catégorie
3. Liens croisés - Vers/depuis les documents liés

🎯 Checklist avant Pull Request¶

Cochez toutes les cases avant de soumettre votre PR :

Code¶

• TypeScript : npm run type-check passe
• ESLint : npm run lint passe
• Tests : npm run test:ci passe (100%)
• Coverage : Pas de régression (vérifier npm test -- --coverage)
• Pas de console.log oubliés
• Pas de commentaires TODO non résolus

Tests¶

• Tests unitaires écrits pour nouveau code
• Tests de régression pour bug fixes
• Tests de composants pour UI critique
• Tous les cas limites couverts

Documentation¶

• README mis à jour si nécessaire
• Documentation technique ajoutée (si applicable)
• Commentaires dans le code (JSDoc si API publique)
• CHANGELOG.md mis à jour

Git¶

• Commits suivent conventional commits
• Messages de commit descriptifs
• Branche à jour avec main/dev
• Pas de conflits de merge

Pull Request¶

• Titre descriptif
• Description détaillée avec contexte
• Screenshots/GIFs si changement UI
• Issues liées mentionnées
• Breaking changes documentés
• Reviewers assignés

🆘 Besoin d'aide ?¶

Resources¶

• Documentation : overview.md
• Architecture : ARCHITECTURE_REFACTOR.md
• Guide de développement : dev.md

Contacts¶

• Issues GitHub : Pour bugs et features
• Discussions : Pour questions générales
• Email : support@probatiovault.com

📚 Exemples de contributions¶

Exemple 1 : Bug fix complet¶

# 1. Créer branche
git checkout -b fix/crypto-conversion-bug

# 2. Écrire test de régression
# src/__tests__/crypto.test.ts
it("REGRESSION TEST: should return 32 bytes not 8", () => {
  expect(result.length).toBe(32);
});

# 3. Vérifier que le test échoue
npm test -- crypto.test.ts

# 4. Corriger le bug
# src/services/crypto.ts

# 5. Vérifier que le test passe
npm test -- crypto.test.ts

# 6. Vérification complète
npm run test:ci && npm run type-check && npm run lint

# 7. Documenter
# docs/bugs/BUG_FIX_CRYPTO_CONVERSION.md

# 8. Commit et push
git add .
git commit -m "fix(crypto): correct WordArray to Uint8Array conversion

- Fixed 8-byte bug by extracting bytes correctly
- Added regression test (32 bytes)
- Updated documentation

Fixes #123"

git push origin fix/crypto-conversion-bug

Exemple 2 : Nouvelle fonctionnalité¶

# 1. Créer branche
git checkout -b feature/document-sharing

# 2. Écrire tests d'abord (TDD)
# src/__tests__/services/sharing.test.ts

# 3. Implémenter la fonctionnalité
# src/services/sharing.ts
# src/components/vault/ShareButton.tsx

# 4. Mettre à jour le store si nécessaire
# src/store/useVaultStore.ts

# 5. Tests complets
npm run test:ci

# 6. Documentation
# Update README.md
# Add docs/guides/SHARING_GUIDE.md

# 7. Commit
git commit -m "feat(vault): add document sharing functionality

- Add ShareButton component
- Implement sharing service with encryption
- Update store with sharing state
- Add comprehensive tests (95% coverage)

Co-authored-by: Alice <alice@example.com>"

Merci de contribuer à ProbatioVault ! 🎉

← Retour à l'index | ← Présentation