Bruno Charest
5280dc7a50
Add extensive project documentation including analysis review, image rendering changelog and guide, contributing guidelines, hidden files configuration guide, PWA documentation suite, roadmap, and dashboard specification.
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).
|