170 lines
4.6 KiB
Markdown
170 lines
4.6 KiB
Markdown
# Contribuer à ObsiGate
|
|
|
|
Merci de votre intérêt pour ObsiGate ! Ce guide décrit les standards de code et le workflow de développement.
|
|
|
|
---
|
|
|
|
## 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
|
|
```
|
|
|
|
### 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).
|