Aller au contenu principal

🧪 Guide de la branche de développement

Vous souhaitez essayer les dernières fonctionnalités avant leur publication officielle ? La branche dev contient des améliorations de pointe et des fonctionnalités expérimentales qui finiront par rejoindre la version principale.

Logiciel expérimental

La branche dev est expérimentale et peut contenir des bogues, des fonctionnalités incomplètes ou des changements incompatibles. Ne l'utilisez que si une certaine instabilité ne vous dérange pas et si vous souhaitez contribuer à améliorer Libre WebUI.

🎯 Qu'est-ce que la branche dev ?​

La branche de développement (dev) est l'endroit où les nouvelles fonctionnalités sont testées avant leur fusion dans la branche stable main. Elle comprend :

  • Les dernières fonctionnalités, encore absentes des versions stables
  • Des corrections de bogues en cours de test
  • Des améliorations expérimentales de l'interface et des fonctionnalités
  • Des optimisations des performances en cours de développement

🚀 Utiliser la branche dev​

Configuration Docker (recommandée)​

Les fichiers Compose de développement montent le socket Docker de l'hôte ; Work fonctionne donc par défaut lorsque Docker est disponible. Les conteneurs des tâches s'exécutent sur le démon de l'hôte et apparaissent dans docker ps. Sous Linux, définissez d'abord DOCKER_GID dans .env.

Avec une instance Ollama externe :

# Clone the repository
git clone https://github.com/libre-webui/libre-webui.git
cd libre-webui

# Switch to dev branch
git checkout dev

# Start the dev image with external Ollama
docker compose -f docker-compose.dev.external-ollama.yml up -d

Docker simple :

# Use the dev branch image
docker run -d -p 3000:3001 -v libre-webui:/app/backend/data --name libre-webui-dev --restart always ghcr.io/libre-webui/libre-webui:dev

Depuis les sources​

# Clone and switch to dev branch
git clone https://github.com/libre-webui/libre-webui.git
cd libre-webui
git checkout dev

# Install dependencies
npm install

# Start development server
npm run dev

Vite peut être prêt avant que le serveur ait terminé ses vérifications de démarrage. Pour un serveur local, le proxy de développement attend jusqu'à 10 secondes que son écouteur réponde avant de transmettre une requête d'API. Il transmet chaque requête une seule fois, écritures comprises, et ne rejoue jamais une requête échouée. Si le serveur reste indisponible, le proxy renvoie un HTTP 503 accompagné d'une indication de nouvelle tentative. Les fichiers statiques du frontend restent accessibles pendant l'attente.

Chat continue de se reconnecter après une panne passagère du serveur, avec des délais plafonnés à 30 secondes. Une connexion réussie réinitialise le délai ; la déconnexion annule les tentatives en attente. Un échec d'authentification met fin à la reconnexion automatique.

Tester Work​

  1. Démarrez Docker et vérifiez que docker info réussit avec le même utilisateur que celui qui exécute le serveur.
  2. Démarrez Libre WebUI depuis les sources avec npm run dev.
  3. Connectez-vous en tant qu'administrateur.
  4. Sélectionnez Work et utilisez Ollama, Ollama Cloud ou un modèle adossé à une extension configurée capable d'employer des outils.

Exécutez les tests ciblés du fournisseur serveur et de la politique des conteneurs avec :

npm run test:work

Les tests valident la politique Docker générée, le confinement des chemins, le cycle de vie et le comportement en matière de capacité, ainsi que les adaptateurs d'outils compatibles OpenAI, Anthropic et Gemini. Consultez Work : espaces de travail isolés pour connaître la totalité des limites de l'environnement d'exécution.

🔄 Rester à jour​

La branche dev est mise à jour fréquemment. Pour récupérer les dernières modifications :

# Update your local dev branch
git pull origin dev

# Refresh the dev Compose stack
docker compose -f docker-compose.dev.external-ollama.yml pull
docker compose -f docker-compose.dev.external-ollama.yml up -d

# Or restart simple Docker
docker pull ghcr.io/libre-webui/libre-webui:dev
docker stop libre-webui-dev && docker rm libre-webui-dev
docker run -d -p 3000:3001 -v libre-webui:/app/backend/data --name libre-webui-dev --restart always ghcr.io/libre-webui/libre-webui:dev

🐛 Vous avez trouvé un bogue ? Aidez-nous à progresser !​

Vos signalements de bogues sont extrêmement précieux. Voici comment signaler efficacement un problème :

Avant de le signaler​

  1. Consultez les problèmes existants : recherchez dans les problèmes GitHub pour éviter les doublons
  2. Essayez la version stable : vérifiez que le bogue n'existe que dans dev (et pas dans la branche main)
  3. Reproduisez-le de manière fiable : pouvez-vous provoquer à nouveau le bogue ?

Signaler un bogue​

🐛 Signaler un bogue sur GitHub

Incluez ces informations :

**Environment:**

- Branch: dev
- Version: [git commit hash or date]
- OS: [Windows/macOS/Linux]
- Browser: [Chrome/Firefox/Safari version]
- Setup: [Docker/Source/etc.]
- Docker: [version and whether `docker info` succeeds, for Work issues]
- Work model/provider: [exact route, when applicable]

**Bug Description:**
Clear description of what went wrong

**Steps to Reproduce:**

1. Go to...
2. Click on...
3. See error...

**Expected Behavior:**
What should have happened

**Actual Behavior:**
What actually happened

**Screenshots/Logs:**
[If applicable, add screenshots or error logs]

**Work Activity:**
[Relevant tool call/result or preview output, with secrets removed]

Obtenir le hachage de votre commit Git​

# Find your current dev branch commit
git rev-parse HEAD

# Or get a short version
git rev-parse --short HEAD

🏆 Contributions et reconnaissance​

En utilisant la branche dev, vous rejoignez notre communauté de test. Les personnes qui contribuent sont reconnues de plusieurs façons :

Reconnaissance des contributions​

  • Mention dans CONTRIBUTORS.md
  • Mention dans les notes de version pour les contributions importantes
  • Attribution de coauteur dans les messages de commit
  • Remerciements particuliers dans les annonces du projet

Personnes qui contribuent actuellement​

Notre formidable communauté comprend :

  • rob - Responsable du projet
  • jm - Amélioration de l'accès réseau
  • Et bien d'autres ! Consultez la liste complète

Vous souhaitez contribuer au code ?​

  1. Dupliquez le dépôt
  2. Créez une branche de fonctionnalité depuis dev : git checkout -b feature/amazing-feature dev
  3. Apportez vos modifications
  4. Soumettez une Pull Request vers la branche dev

Consultez nos consignes de contribution pour des instructions détaillées et notre charte de la communauté pour les principes éthiques et le modèle de gouvernance du projet.

Contrôles des Pull Requests​

Chaque Pull Request, y compris une Pull Request empilée vers une branche intermédiaire de fonctionnalité ou de correction, exécute le workflow Format & Lint. Ses tâches indépendantes vérifient la mise en forme, le lint de l'interface et du serveur, les types TypeScript, les tests des paquets et de régression, ainsi que la suite Playwright dans le navigateur. Chromium exécute la suite complète dans le navigateur. WebKit et Firefox exécutent aussi les parcours critiques d'authentification, de streaming, de boîtes de dialogue, d'onglets, d'automatisation, de stockage, de Work et de lecture vocale. Chaque moteur s'exécute dans sa propre tâche CI, et les exécutions qui échouent téléversent des résultats de test distincts.

L'archive npm testée est installée dans un nouveau répertoire consommateur sous Linux, macOS et Windows, avec Node 22.22 et Node 24. Ces vérifications installent de vraies dépendances de production sans emprunter le node_modules de la copie de travail, puis vérifient le démarrage de la CLI, la disponibilité, le service du frontend et la conservation des données après un redémarrage. Exécutez la même vérification en local après npm run build avec npm run test:package-install ; passez une archive ou un répertoire contenant une seule archive pour tester un artefact précis. Une installation propre nécessite l'accès au registre ainsi que les prérequis habituels de la plateforme pour compiler les modules natifs lorsqu'une dépendance précompilée n'est pas disponible.

Une tâche Work Computer distincte construit l'image graphique à partir de la base épinglée de l'environnement d'exécution et lance le véritable test de régression des interactions. Avec TEST_WORK_COMPUTER=1, un démon Docker ou une image manquante fait échouer la vérification au lieu de la faire ignorer. Pour reproduire ce test en local, définissez cet indicateur ainsi que WORK_COMPUTER_TEST_IMAGE sur une image de test construite séparément, puis exécutez npm run test:work-computer. Hors mode obligatoire, les exécutions locales signalent toujours un test ignoré lorsque la fixture graphique facultative est absente.

Cette matrice ajoute des vérifications pour les surfaces prises en charge ; elle n'active pas de combinaisons non prises en charge. Les identifiants CLI propres à un nœud restent inaccessibles aux workers d'équipe externes.

CodeQL couvre le code JavaScript/TypeScript, Python et les workflows à chaque Pull Request. Les serveurs de fournisseurs Python exécutables sous examples/ sont explicitement classés comme code dans .gitattributes, afin que la détection des langages de GitHub les prenne en compte. La configuration gérée distincte Code Quality doit inclure à la fois JavaScript/TypeScript et Python. Si des résultats historiques subsistent après une correction, vérifiez la révision analysée et la couverture des langages, puis actualisez l'analyse concernée après la publication de la modification. Ne rejetez pas des résultats valides et ne modifiez pas un comportement asynchrone correct dans le seul but d'améliorer une note affichée.

Le workflow Electron Dev Build crée également des paquets pour macOS, Windows et Linux. Les compilations macOS des Pull Requests conservent la signature ad hoc du projet, sans identifiants, afin de vérifier l'application empaquetée avant son téléversement. Le workflow de Pull Request ne reçoit pas d'identifiants Developer ID ni de notarisation.

Le workflow Docker Build Test and Push compile les images amd64 et arm64 pour chaque Pull Request, y compris les Pull Requests empilées vers des branches intermédiaires. Les compilations de Pull Request ne se connectent pas à un registre de conteneurs, ne poussent pas de condensats d'images et ne publient pas de manifeste multiarchitecture.

Exécutez les mêmes contrôles au niveau de l'application localement avant d'ouvrir une Pull Request :

npm run format:check
npm run lint
npm run test:package
npm run test:e2e

⚠️ Remarques importantes​

Sécurité des données​

  • Sauvegardez vos données avant de passer à la branche dev
  • Les fichiers des tâches Work résident dans des volumes nommés Docker libre-work-* distincts. Sauvegardez-les séparément du répertoire de données SQLite avant de tester des modifications destructrices du cycle de vie des tâches ou des utilisateurs.
  • Utilisez un volume Docker séparé pour les tests de dev : 
    # Use different volume name for dev
    docker run -d -p 3000:3001 -v libre-webui-dev:/app/backend/data --name libre-webui-dev ghcr.io/libre-webui/libre-webui:dev

Problèmes possibles​

  • Des changements incompatibles peuvent nécessiter des mises à jour de configuration
  • Des fonctionnalités peuvent être incomplètes ou changer sans préavis
  • Les performances peuvent varier pendant les tests d'optimisation
  • Des éléments de l'interface peuvent avoir un aspect différent ou un comportement inattendu

Quand utiliser la version stable​

Revenez à la branche stable main si vous :

  • Avez besoin de fiabilité pour des tâches importantes
  • Rencontrez trop de bogues
  • Souhaitez une expérience stable et testée
# Switch back to stable
git checkout main
docker compose -f docker-compose.external-ollama.yml pull
docker compose -f docker-compose.external-ollama.yml up -d

🌟 Rejoindre la communauté​

Prêt à nous aider à façonner l'avenir de Libre WebUI ? 🚀

Vos tests, vos retours et vos contributions sur la branche dev améliorent directement l'expérience de l'ensemble des utilisateurs. Merci de faire partie de notre communauté de développement !