Passa al contenuto principale

🧪 Guida al branch di sviluppo

Vuoi provare le funzionalità più recenti prima del rilascio ufficiale? Il branch dev contiene miglioramenti all'avanguardia e funzionalità sperimentali che verranno infine integrate nella release principale.

Software sperimentale

Il branch dev è sperimentale e può contenere bug, funzionalità incomplete o modifiche incompatibili. Usalo solo se accetti una possibile instabilità e vuoi contribuire a migliorare Libre WebUI.

🎯 Che cos'è il branch dev?​

Il branch di sviluppo (dev) è il luogo in cui le nuove funzionalità vengono provate prima di essere integrate nel branch stabile main. Include:

  • Funzionalità recenti non ancora presenti nelle release stabili
  • Correzioni di bug in fase di verifica
  • Miglioramenti sperimentali all'interfaccia e alle funzionalità
  • Ottimizzazioni delle prestazioni in fase di sviluppo

🚀 Come usare il branch dev​

Configurazione Docker (consigliata)​

I file Compose di sviluppo montano il socket Docker dell'host, quindi Work funziona per impostazione predefinita quando Docker è disponibile. I container delle attività vengono eseguiti sul daemon dell'host e compaiono in docker ps. Su Linux, imposta prima DOCKER_GID in .env.

Con Ollama esterno:

# 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 semplice:

# 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

Dal codice sorgente​

# 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 può essere pronto prima che il backend completi i controlli di avvio. Con un backend locale, il proxy di sviluppo attende fino a 10 secondi la comparsa del suo listener prima di inoltrare una richiesta API. Inoltra ogni richiesta una sola volta, comprese le scritture; non ripete le richieste fallite. Se il backend resta non disponibile, il proxy risponde con HTTP 503 e un suggerimento di riprovare. I file statici del frontend restano disponibili durante l'attesa.

La chat continua a riconnettersi dopo interruzioni temporanee del backend, con ritardi limitati a 30 secondi. Una connessione riuscita azzera il ritardo; l'uscita dall'account annulla i tentativi in sospeso. Gli errori di autenticazione interrompono la riconnessione automatica.

Verificare Work​

  1. Avvia Docker e verifica che docker info venga eseguito correttamente dallo stesso utente che avvia il backend.
  2. Avvia Libre WebUI dal codice sorgente con npm run dev.
  3. Accedi come amministratore.
  4. Seleziona Work e usa Ollama, Ollama Cloud o un modello configurato tramite plugin che supporti gli strumenti.

Esegui i test mirati dei provider del backend e dei criteri dei container con:

npm run test:work

I test convalidano i criteri Docker generati, il contenimento dei percorsi, il comportamento del ciclo di vita e della capacità, nonché gli adattatori degli strumenti compatibili con OpenAI, Anthropic e Gemini. Consulta Work: aree di lavoro isolate per tutti i limiti del runtime.

🔄 Rimanere aggiornati​

Il branch dev viene aggiornato spesso. Per ottenere le modifiche più recenti:

# 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

🐛 Hai trovato un bug? Aiutaci a migliorare!​

Le tue segnalazioni di bug sono estremamente preziose. Ecco come segnalare i problemi in modo efficace:

Prima di segnalare​

  1. Controlla i problemi esistenti: cerca tra i problemi GitHub per evitare duplicati
  2. Prova la versione stabile: verifica che il bug esista solo in dev (e non nel branch main)
  3. Riproducilo con regolarità: riesci a far comparire nuovamente il bug?

Come segnalare i bug​

🐛 Segnala un bug su GitHub

Includi queste informazioni:

**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]

Ottenere l'hash del commit Git​

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

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

🏆 Contributi e riconoscimenti​

Usando il branch dev entri a far parte della nostra comunità di tester. I collaboratori ricevono riconoscimenti in diversi modi:

Riconoscimenti per i collaboratori​

  • Inserimento in CONTRIBUTORS.md
  • Menzione nelle note di rilascio per i contributi significativi
  • Attribuzione come coautore nei messaggi di commit
  • Ringraziamenti speciali negli annunci del progetto

Collaboratori attuali​

La nostra straordinaria comunità include:

  • rob - Responsabile del progetto
  • jm - Miglioramento dell'accesso di rete
  • E molti altri! Consulta l'elenco completo

Vuoi contribuire al codice?​

  1. Crea un fork del repository
  2. Crea un branch della funzionalità da dev: git checkout -b feature/amazing-feature dev
  3. Apporta le modifiche
  4. Invia una pull request verso il branch dev

Consulta le Linee guida per contribuire per istruzioni dettagliate e il nostro Statuto della comunità per le linee guida etiche e il modello di governance del progetto.

Controlli delle pull request​

Ogni pull request, comprese quelle sovrapposte verso un branch intermedio di funzionalità o correzione, esegue il workflow Format & Lint. I suoi job indipendenti controllano formattazione, lint del frontend e del backend, tipi TypeScript, test dei pacchetti e di regressione e la suite Playwright per browser. Chromium esegue l'intera suite per browser. WebKit e Firefox eseguono inoltre i flussi critici di autenticazione, streaming, finestre di dialogo, schede, automazioni, archiviazione, Work e riproduzione vocale. Ogni motore gira in un proprio job di CI e le esecuzioni non riuscite caricano risultati di test separati.

Il tarball npm testato viene installato in una nuova directory consumer su Linux, macOS e Windows, con Node 22.22 e con Node 24. Questi controlli installano le vere dipendenze di produzione senza prendere in prestito i node_modules del checkout, poi verificano l'avvio della CLI, la prontezza, il servizio del frontend e la persistenza dei dati dopo un riavvio. Esegui lo stesso controllo in locale dopo npm run build con npm run test:package-install; passa un tarball o una directory che ne contiene uno per testare un artefatto specifico. Un'installazione pulita richiede l'accesso al registry e i normali prerequisiti della piattaforma per compilare i moduli nativi quando una dipendenza precompilata non è disponibile.

Un job separato per Work Computer compila l'immagine GUI dalla base fissata del runtime ed esegue il vero test di regressione dell'interazione. TEST_WORK_COMPUTER=1 fa fallire il controllo, invece di saltarlo, quando mancano il demone Docker o l'immagine. Per riprodurlo in locale, imposta quel flag e WORK_COMPUTER_TEST_IMAGE su un'immagine di test compilata a parte, poi esegui npm run test:work-computer. Senza la modalità obbligatoria, le esecuzioni locali segnalano comunque un salto quando la fixture GUI opzionale è assente.

Questa matrice aggiunge controlli per le superfici supportate; non abilita combinazioni non supportate. Le credenziali CLI locali al nodo restano non disponibili per i worker esterni del team.

CodeQL copre il codice JavaScript/TypeScript, Python e dei workflow in ogni pull request. I server provider Python eseguibili in examples/ sono classificati esplicitamente come codice in .gitattributes, così il rilevamento dei linguaggi di GitHub li include. La configurazione gestita separata di Code Quality deve includere sia JavaScript/TypeScript sia Python. Se dopo una correzione restano risultati storici, verifica la revisione analizzata e la copertura dei linguaggi e aggiorna l'analisi pertinente dopo aver pubblicato la modifica. Non ignorare risultati validi e non modificare un comportamento asincrono corretto solo per migliorare un punteggio mostrato.

Anche il workflow Electron Dev Build crea pacchetti per macOS, Windows e Linux. Le build macOS delle pull request mantengono la firma ad hoc del progetto, priva di credenziali, così l'applicazione pacchettizzata può essere verificata prima del caricamento. Il workflow delle pull request non riceve credenziali Developer ID o di autenticazione notarile.

Il workflow Docker Build Test and Push crea immagini amd64 e arm64 per ogni pull request, comprese quelle sovrapposte verso branch intermedi. Le build delle pull request non accedono a un registro di container, non inviano digest di immagini né pubblicano un manifest multiarchitettura.

Esegui localmente gli stessi controlli a livello di applicazione prima di aprire una pull request:

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

⚠️ Note importanti​

Sicurezza dei dati​

  • Esegui il backup dei dati prima di passare al branch dev
  • I file delle attività Work risiedono in volumi Docker con nome libre-work-* separati. Esegui un backup distinto da quello della directory dei dati SQLite prima di provare modifiche distruttive al ciclo di vita delle attività o degli utenti.
  • Usa un volume Docker separato per i test 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

Possibili problemi​

  • Le modifiche incompatibili possono richiedere aggiornamenti alla configurazione
  • Le funzionalità possono essere incomplete o cambiare senza preavviso
  • Le prestazioni possono variare durante la verifica delle ottimizzazioni
  • Gli elementi dell'interfaccia potrebbero apparire diversi o comportarsi in modo imprevisto

Quando usare la versione stabile​

Torna al branch stabile main se:

  • Ti serve affidabilità per attività importanti
  • Riscontri troppi bug
  • Vuoi un'esperienza verificata e stabile
# 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

🌟 Unisciti alla comunità​

Vuoi contribuire a plasmare il futuro di Libre WebUI? 🚀

I tuoi test, commenti e contributi sul branch dev migliorano direttamente l'esperienza di tutti gli utenti. Grazie di far parte della nostra comunità di sviluppo!