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. 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

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 §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 :

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

# 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().

# 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

# 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

# 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.