Перейти до основного вмісту

🧪 Посібник із гілки розробки

Хочете випробувати нові функції до офіційного випуску? Гілка dev містить найновіші вдосконалення й експериментальні функції, які згодом потраплять до основного випуску.

Експериментальне програмне забезпечення

Гілка dev експериментальна й може містити помилки, незавершені функції або несумісні зміни. Використовуйте її, лише якщо готові до нестабільності й хочете допомогти вдосконалити Libre WebUI.

🎯 Що таке гілка dev?​

Гілка розробки (dev) призначена для перевірки нових функцій до злиття зі стабільною main. Вона містить:

  • Нові функції, яких ще немає у стабільних випусках
  • Виправлення помилок на перевірці
  • Експериментальні вдосконалення інтерфейсу й можливостей
  • Оптимізації швидкодії в розробці

🚀 Використання гілки dev​

Налаштування Docker (рекомендовано)​

Файли Compose для розробки підключають сокет Docker хоста, тому Work типово працює, коли Docker доступний. Контейнери завдань виконуються демоном хоста й видимі в docker ps. У Linux спочатку задайте DOCKER_GID у .env.

Із зовнішньою Ollama:

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

# 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

Із вихідного коду​

# 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 може стати готовим раніше, ніж серверна частина завершить перевірки запуску. Для локальної серверної частини проксі середовища розробки чекає на її слухач до 10 секунд, перш ніж переслати запит до API. Кожен запит пересилається один раз, зокрема запис; невдалі запити не повторюються. Якщо серверна частина залишається недоступною, проксі повертає HTTP 503 із підказкою повторити спробу. Статичні файли клієнтської частини лишаються доступними під час очікування.

Чат продовжує перепідключатися після тимчасових збоїв серверної частини із затримкою не більше 30 секунд. Успішне з’єднання скидає затримку; вихід із системи скасовує заплановані спроби. Помилки автентифікації зупиняють автоматичне перепідключення.

Перевірка Work​

  1. Запустіть Docker і переконайтеся, що docker info працює від того самого користувача, що й серверна частина.
  2. Запустіть Libre WebUI з вихідного коду командою npm run dev.
  3. Увійдіть як адміністратор.
  4. Виберіть Work і модель Ollama, Ollama Cloud або налаштованого плагіна з інструментами.

Запустіть цільові тести постачальників серверної частини й політики контейнерів:

npm run test:work

Тести перевіряють створену політику Docker, обмеження шляхів, життєвий цикл, місткість і адаптери інструментів OpenAI-compatible, Anthropic та Gemini. Повну межу описано в Work: ізольовані робочі простори.

🔄 Отримання оновлень​

Гілка dev оновлюється часто. Щоб отримати останні зміни:

# 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

🐛 Знайшли помилку? Допоможіть удосконалити проєкт!​

Ваші повідомлення дуже цінні. Щоб ефективно повідомити про проблему:

Перед повідомленням​

  1. Перевірте наявні звернення: пошукайте в GitHub Issues, щоб уникнути дубліката
  2. Спробуйте стабільну версію: підтвердьте, що помилка існує лише в dev, а не main
  3. Доможіться відтворюваності: чи можете повторити помилку?

Як повідомити про помилку​

🐛 Повідомити про помилку в GitHub

Додайте такі відомості:

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

Отримання хеша коміту Git​

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

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

🏆 Участь і визнання​

Використовуючи dev, ви стаєте частиною спільноти тестувальників. Внесок відзначається кількома способами:

Визнання учасників​

  • Зазначення в CONTRIBUTORS.md
  • Згадка в примітках до випуску за значний внесок
  • Співавторство в повідомленнях комітів
  • Особлива подяка в оголошеннях проєкту

Поточні учасники​

У нашій спільноті, серед інших:

  • rob - Супровідник проєкту
  • jm - Удосконалення мережевого доступу
  • І багато інших! Див. повний список

Хочете додати код?​

  1. Створіть відгалуження репозиторію
  2. Створіть гілку функції від dev: git checkout -b feature/amazing-feature dev
  3. Внесіть зміни
  4. Надішліть Pull Request до гілки dev

Докладні вказівки див. в посібнику для учасників, а етичні принципи й керування — у Community Charter.

Перевірки Pull Request​

Кожен pull request, зокрема складений до проміжної гілки, запускає процес Format & Lint. Незалежні завдання перевіряють форматування, аналіз інтерфейсу й серверної частини, типи TypeScript, пакетні та регресійні тести й браузерний набір Playwright. Chromium проходить увесь браузерний набір. WebKit і Firefox додатково перевіряють критичні сценарії автентифікації, потокової передачі, діалогів, вкладок, автоматизацій, сховища, Work і відтворення мовлення. Кожен рушій запускається в окремому завданні CI, а невдалі запуски завантажують окремі результати тестів.

Перевірений tarball npm встановлюється в новий каталог-споживач у Linux, macOS і Windows із Node 22.22 та Node 24. Ці перевірки встановлюють справжні робочі залежності, не запозичуючи node_modules з checkout, а потім перевіряють запуск CLI, готовність, віддавання фронтенду та збереження даних після перезапуску. Ту саму перевірку можна запустити локально після npm run build командою npm run test:package-install; щоб перевірити конкретний артефакт, передайте tarball або каталог з одним tarball. Для чистого встановлення потрібен доступ до реєстру, а також звичайні передумови платформи для збирання нативних модулів, якщо готової збірки залежності немає.

Окреме завдання Work Computer збирає образ GUI із закріпленої бази середовища виконання й запускає справжній регресійний тест взаємодії. TEST_WORK_COMPUTER=1 змушує перевірку завершитися помилкою, а не пропускатися, якщо немає демона Docker або образу. Щоб відтворити це локально, задайте цей прапорець і WORK_COMPUTER_TEST_IMAGE зі значенням окремо зібраного тестового образу, а потім виконайте npm run test:work-computer. Без обов’язкового режиму локальні запуски, як і раніше, повідомляють про пропуск, якщо необов’язкової GUI-фікстури немає.

Ця матриця додає перевірки для підтримуваних поверхонь; вона не вмикає непідтримуваних комбінацій. Локальні для вузла облікові дані CLI, як і раніше, недоступні зовнішнім виконавцям команди.

CodeQL охоплює код JavaScript/TypeScript, Python і процесів у кожному pull request. Виконувані сервери провайдерів на Python у examples/ явно позначено як код у .gitattributes, тож визначення мов GitHub їх враховує. Окреме кероване налаштування Code Quality має охоплювати і JavaScript/TypeScript, і Python. Якщо після виправлення залишаються історичні знахідки, перевірте проаналізовану ревізію та охоплення мов і оновіть відповідний аналіз після публікації зміни. Не відхиляйте обґрунтовані знахідки й не змінюйте правильну асинхронну поведінку лише заради кращої оцінки на екрані.

Процес Electron Dev Build також пакує артефакти macOS, Windows і Linux. Збірки macOS для pull request зберігають спеціальний підпис без облікових даних, щоб програму можна було перевірити до завантаження. Процес не отримує даних Developer ID або нотаріального посвідчення.

Docker Build Test and Push збирає образи amd64 і arm64 для кожного pull request, зокрема складених. Збірки не входять до реєстру, не надсилають digest і не публікують багатоархітектурний маніфест.

До відкриття pull request виконайте ті самі перевірки локально:

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

⚠️ Важливі зауваження​

Безпека даних​

  • Створіть резервну копію до переходу на dev
  • Файли завдань Work містяться в окремих іменованих томах Docker libre-work-*. Копіюйте їх окремо від SQLite до руйнівних перевірок життєвого циклу завдань або користувачів.
  • Використовуйте окремий том Docker для 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

Можливі проблеми​

  • Несумісні зміни можуть потребувати налаштування
  • Функції можуть бути незавершеними або змінюватися без попередження
  • Швидкодія може різнитися під час перевірки оптимізацій
  • Елементи інтерфейсу можуть виглядати або поводитися інакше

Коли використовувати стабільну версію​

Поверніться до стабільної main, якщо:

  • Потрібна надійність для важливої роботи
  • Помилок забагато
  • Потрібне перевірене стабільне середовище
# 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

🌟 Долучайтеся до спільноти​

Готові допомагати формувати майбутнє Libre WebUI? 🚀

Ваші тести, відгуки й внесок у dev безпосередньо поліпшують роботу всіх користувачів. Дякуємо за участь у спільноті розробки!