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

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. Execuções do navegador com falha enviam seus resultados do Playwright para depuração.

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!