Pular para o conteúdo principal

🧪 Guia da branch de desenvolvimento

Quer experimentar os recursos mais recentes antes do lançamento oficial? A branch dev contém melhorias de ponta e recursos experimentais que futuramente chegarão ao lançamento principal.

Software experimental

A branch dev é experimental e pode conter bugs, recursos incompletos ou alterações incompatíveis. Use-a somente se você aceitar uma possível instabilidade e quiser ajudar a melhorar o Libre WebUI.

🎯 O que é a branch dev?​

A branch de desenvolvimento (dev) é o lugar onde novos recursos são testados antes de serem mesclados à branch estável main. Ela inclui:

  • Recursos mais recentes que ainda não estão em versões estáveis
  • Correções de bugs em teste
  • Melhorias experimentais na interface e nas funcionalidades
  • Otimizações de desempenho em desenvolvimento

🚀 Como usar a branch dev​

Configuração com Docker (recomendada)​

Os arquivos Compose de desenvolvimento montam o socket Docker do host; portanto, o Work funciona por padrão quando o Docker está disponível. Os contêineres das tarefas são executados no daemon do host e aparecem em docker ps. No Linux, primeiro defina DOCKER_GID em .env.

Com Ollama externo:

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

# 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

A partir do código-fonte​

# 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

O Vite pode ficar pronto antes de o backend concluir suas verificações de inicialização. Para um backend local, o proxy de desenvolvimento espera até 10 segundos pelo listener antes de encaminhar uma requisição de API. Ele encaminha cada requisição uma única vez, inclusive as de escrita; requisições que falham não são repetidas. Se o backend continuar indisponível, o proxy devolve HTTP 503 com uma dica de nova tentativa. Os arquivos estáticos do frontend continuam disponíveis durante a espera.

O chat segue tentando reconectar depois de quedas passageiras do backend, com intervalos limitados a 30 segundos. Uma conexão bem-sucedida zera o intervalo; sair da conta cancela as tentativas pendentes. Falhas de autenticação interrompem a reconexão automática.

Teste do Work​

  1. Inicie o Docker e confirme que docker info funciona com o mesmo usuário que executa o backend.
  2. Inicie o Libre WebUI a partir do código-fonte com npm run dev.
  3. Entre como administrador.
  4. Selecione Work e use um modelo Ollama, Ollama Cloud ou fornecido por plugin configurado que seja compatível com ferramentas.

Execute os testes específicos do provedor do backend e da política de contêineres com:

npm run test:work

Os testes validam a política gerada do Docker, o confinamento de caminhos, o ciclo de vida e o comportamento de capacidade, além dos adaptadores de ferramentas compatíveis com OpenAI, Anthropic e Gemini. Consulte Work: espaços de trabalho isolados para conhecer toda a barreira do ambiente de execução.

🔄 Como se manter atualizado​

A branch dev é atualizada com frequência. Para obter as alterações mais recentes:

# 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

🐛 Encontrou um bug? Ajude-nos a melhorar!​

Seus relatos de bugs são extremamente valiosos! Veja como informar problemas de modo eficaz:

Antes de relatar​

  1. Verifique os problemas existentes: pesquise nas Issues do GitHub para evitar duplicatas
  2. Experimente a versão estável: confirme que o bug existe apenas em dev (e não na branch main)
  3. Reproduza de forma consistente: você consegue fazer o bug acontecer de novo?

Como relatar bugs​

🐛 Relate um bug no GitHub

Inclua estas informações:

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

Obtenha o hash do seu commit Git​

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

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

🏆 Contribuição e reconhecimento​

Usar a branch dev faz de você parte da nossa comunidade de testes! Os contribuidores são reconhecidos de várias formas:

Reconhecimento dos contribuidores​

  • Incluídos em CONTRIBUTORS.md
  • Mencionados nas notas de lançamento por contribuições significativas
  • Atribuição como coautor nas mensagens de commit
  • Agradecimento especial nos anúncios do projeto

Contribuidores atuais​

Nossa incrível comunidade inclui:

  • rob - Mantenedor do projeto
  • jm - Melhoria de acesso à rede
  • E mais contribuidores! Consulte a lista completa

Quer contribuir com código?​

  1. Faça fork do repositório
  2. Crie uma branch de recurso a partir de dev: git checkout -b feature/amazing-feature dev
  3. Faça suas alterações
  4. Envie um pull request para a branch dev

Consulte nossas Diretrizes de contribuição para obter instruções detalhadas e nossa Carta da comunidade para conhecer as diretrizes éticas e o modelo de governança do projeto.

Verificações dos pull requests​

Todo pull request, inclusive um pull request empilhado para uma branch intermediária de recurso ou correção, executa o workflow Format & Lint. Suas tarefas independentes verificam formatação, lint do frontend e backend, tipos TypeScript, testes de pacotes e regressão e a suíte de navegador do Playwright. O Chromium executa a suíte de navegador completa. O WebKit e o Firefox também executam os fluxos críticos de autenticação, streaming, diálogos, abas, automações, armazenamento, Work e reprodução de fala. Cada motor de navegador roda na própria tarefa de CI, e execuções com falha enviam resultados de teste separados.

O tarball npm testado é instalado em um novo diretório consumidor no Linux, no macOS e no Windows, usando tanto o Node 22.22 quanto o Node 24. Essas verificações instalam dependências reais de produção sem aproveitar o node_modules do checkout e depois verificam a inicialização da CLI, a prontidão, o serviço do frontend e a preservação dos dados após uma reinicialização. Para executar a mesma verificação localmente, rode npm run test:package-install depois de npm run build; passe um tarball ou um diretório que contenha um único tarball para testar um artefato específico. Uma instalação limpa precisa de acesso ao registro e, quando uma dependência pré-compilada não estiver disponível, dos pré-requisitos normais da plataforma para compilar módulos nativos.

Uma tarefa separada do Work Computer compila a imagem GUI a partir da base fixada do runtime e executa a regressão real de interação. TEST_WORK_COMPUTER=1 faz com que a ausência do daemon do Docker ou da imagem reprove a verificação em vez de ignorá-la. Para reproduzir localmente, defina essa flag e WORK_COMPUTER_TEST_IMAGE apontando para uma imagem de teste compilada separadamente e depois execute npm run test:work-computer. Fora do modo obrigatório, as execuções locais continuam informando que o teste foi ignorado quando o fixture opcional de GUI não está presente.

Essa matriz adiciona verificações para as superfícies compatíveis; ela não habilita combinações sem suporte. Credenciais de CLI locais do nó continuam indisponíveis para workers externos de equipe.

O CodeQL cobre JavaScript/TypeScript, Python e código de workflows em todo pull request. Os servidores de provedor em Python executáveis em examples/ são classificados explicitamente como código em .gitattributes, para que a detecção de linguagens do GitHub os inclua. A configuração gerenciada separada de Code Quality deve incluir tanto JavaScript/TypeScript quanto Python. Se achados antigos continuarem aparecendo depois de uma correção, verifique a revisão analisada e a cobertura de linguagens e atualize a análise aplicável depois de publicar a alteração. Não descarte achados válidos nem altere um comportamento assíncrono correto só para melhorar uma nota exibida.

O workflow Electron Dev Build também empacota artifacts para macOS, Windows e Linux. As compilações de pull requests para macOS mantêm a assinatura ad-hoc sem credenciais do projeto para que o aplicativo empacotado possa ser verificado antes do envio. O workflow de pull requests não recebe credenciais de Developer ID nem de notarização.

O workflow Docker Build Test and Push compila imagens amd64 e arm64 para todo pull request, inclusive pull requests empilhados para branches intermediárias. As compilações de pull requests não entram em um registro de contêineres, não enviam digests de imagem nem publicam um manifesto multi-arquitetura.

Execute localmente as mesmas verificações no nível do aplicativo antes de abrir um pull request:

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

⚠️ Observações importantes​

Segurança dos dados​

  • Faça backup dos seus dados antes de mudar para a branch dev
  • Os arquivos das tarefas do Work ficam em volumes nomeados separados do Docker, libre-work-*. Faça backup deles separadamente do diretório de dados do SQLite antes de testar alterações destrutivas no ciclo de vida de tarefas ou usuários.
  • Use um volume Docker separado para os testes em 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

Possíveis problemas​

  • Alterações incompatíveis podem exigir atualizações de configuração
  • Recursos podem estar incompletos ou mudar sem aviso
  • O desempenho pode variar enquanto as otimizações são testadas
  • Elementos da interface podem parecer diferentes ou se comportar de modo inesperado

Quando usar a versão estável​

Volte para a branch estável main se você:

  • Precisa de confiabilidade para trabalhos importantes
  • Está enfrentando bugs demais
  • Quer uma experiência testada e estável
# 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

🌟 Participe da comunidade​

Pronto para ajudar a moldar o futuro do Libre WebUI? 🚀

Seus testes, feedback e contribuições na branch dev melhoram diretamente a experiência de todos os usuários. Agradecemos por fazer parte da nossa comunidade de desenvolvimento!