ObsiGate/docs/CONTRIBUTING.md

# Contribuer à ObsiGate

Merci de votre intérêt pour ObsiGate ! Ce guide décrit les standards de code et le workflow de développement.

> **⚠️ À lire avant toute contribution** : la méthode de livraison complète (Definition of Done :
> tests, docs, commit, push, CI) est définie dans [`DELIVERY_WORKFLOW.md`](./DELIVERY_WORKFLOW.md).
> Ce document-ci détaille uniquement les standards de code.

---

## Prérequis

- **Python** 3.11+
- **Docker** >= 20.10 (pour les tests conteneurisés)
- **Git**

---

## Lancer en mode développement

### 1. Cloner et installer les dépendances

```bash
git clone https://git.dracodev.net/Projets/ObsiGate.git
cd ObsiGate

# Créer un environnement virtuel
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

pip install -r backend/requirements.txt

# Activer les hooks git versionnés (.githooks) : incrément automatique de la
# version livrée (VERSION) à chaque commit + publication du tag vX.Y.Z au push.
scripts/install-hooks.sh
```

> **Hooks obligatoires** : `scripts/install-hooks.sh` pose `core.hooksPath=.githooks` et
> `push.followTags=true`. Sans eux, la version (`VERSION`) ne suit plus les livraisons et le
> CI reste sur un numéro obsolète. Détail : [DEVELOPMENT_AND_RELEASES.md](./DEVELOPMENT_AND_RELEASES.md) §3.
> Contournement ponctuel d'un commit : `SKIP_VERSION_BUMP=1 git commit …`.

### 2. Configurer les vaults de test

Créez un dossier `test_vault/` (ignoré par `.gitignore`) avec quelques fichiers `.md` :

```bash
mkdir -p test_vault
echo -e "---\ntags: [test, demo]\ntitle: Note de test\n---\n# Hello\nCeci est une note de test." > test_vault/test.md
```

### 3. Lancer le serveur de développement

```bash
# Définir les variables de vault
export VAULT_1_NAME=Test
export VAULT_1_PATH=$(pwd)/test_vault

# Lancer avec rechargement automatique
uvicorn backend.main:app --host 0.0.0.0 --port 8080 --reload
```

L'interface est accessible sur `http://localhost:8080`.

---

## Standards de code

### Python (backend/)

- **Docstrings** : chaque fonction publique doit avoir une docstring complète (style Google/Sphinx).
- **Types** : utiliser les annotations de type sur tous les paramètres et retours.
- **Modèles** : chaque endpoint FastAPI doit avoir un `response_model` Pydantic.
- **Imports** : groupés par standard lib, third-party, local — séparés par une ligne vide.
- **Logging** : utiliser le logger du module (`logger = logging.getLogger("obsigate.xxx")`).
- **Sécurité** : tout chemin fichier fourni par l'utilisateur doit passer par `_resolve_safe_path()`.

```python
# Exemple de fonction conforme
def ma_fonction(param: str, count: int = 10) -> List[str]:
    """Description courte de la fonction.

    Args:
        param: Description du paramètre.
        count: Nombre maximum de résultats.

    Returns:
        Liste de chaînes correspondantes.
    """
    ...
```

### JavaScript (frontend/)

- **Vanilla JS uniquement** — zéro framework, zéro dépendance npm.
- **Fonctions nommées** : pas de logique inline dans les event listeners.
- **`"use strict"`** : le code est wrappé dans une IIFE stricte.
- **Commentaires** : documenter toute logique non-triviale avec des commentaires en ligne.
- **Gestion d'erreurs** : toujours `try/catch` les appels `api()`, afficher un toast en cas d'erreur.
- **Performance** : utiliser `safeCreateIcons()` (debounced) plutôt que `lucide.createIcons()` directement.

### CSS (frontend/)

- **CSS variables** : toutes les couleurs et valeurs de spacing doivent utiliser des variables CSS définies dans `:root`.
- **Pas de valeurs hardcodées** : utiliser `var(--danger)` au lieu de `#ff7b72`, etc.
- **Thèmes** : toute nouvelle couleur doit être déclarée dans les deux blocs de thème (`dark` et `light`).
- **Mobile-first** : vérifier le rendu mobile pour tout changement de layout.

---

## Tester les changements

### Test local rapide

```bash
# Lancer le serveur
export VAULT_1_NAME=Test && export VAULT_1_PATH=$(pwd)/test_vault
uvicorn backend.main:app --port 8080 --reload

# Vérifier le health check
curl http://localhost:8080/api/health

# Vérifier l'indexation
curl http://localhost:8080/api/vaults

# Tester la recherche
curl "http://localhost:8080/api/search?q=test"
```

### Test Docker

```bash
# Build local
docker build -t obsigate:test .

# Lancer avec une vault de test
docker run --rm -p 8080:8080 \
  -v $(pwd)/test_vault:/vaults/Test:ro \
  -e VAULT_1_NAME=Test \
  -e VAULT_1_PATH=/vaults/Test \
  obsigate:test

# Vérifier le healthcheck
curl http://localhost:8080/api/health
```

### Vérifications avant commit

1. **API** : tous les endpoints retournent les bons codes HTTP.
2. **Frontend** : tester en thème clair ET sombre.
3. **Mobile** : tester à 375px de largeur (DevTools).
4. **Erreurs** : vérifier que les toasts s'affichent correctement sur erreur réseau.
5. **Performance** : pas de régression visible sur le temps de chargement.

---

## Workflow Git

1. **Fork** le projet
2. Créer une branche depuis `main` : `git checkout -b feature/ma-feature`
3. Commiter avec des messages clairs en français ou anglais
4. Pousser et créer une **Pull Request**
5. Attendre la review avant de merger

---

## Structure des commits

```
type: description courte

Corps optionnel avec plus de détails.
```

Types : `feat`, `fix`, `perf`, `refactor`, `docs`, `style`, `chore`, `test`

---

## Questions ?

Ouvrez une issue sur [git.dracodev.net/Projets/ObsiGate/issues](https://git.dracodev.net/Projets/ObsiGate/issues).