ZhuchkaTriplesix · Oct 18, 2026 · Oct 18, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -120,4 +120,7 @@ If you fix something **after** pushing a release tag, either move the tag (only
 the team agrees and the release is not yet consumed) or ship a **new** semver
 (update `pubspec.yaml` / `CHANGELOG.md`) and push a new tag. See
 [docs/tags-and-releases.md](docs/tags-and-releases.md) and
-[docs/release-checklist.md](docs/release-checklist.md).
+[docs/release-checklist.md](docs/release-checklist.md). Betas
+(`X.Y.Z-beta.N`, a GitHub pre-release only Beta-channel users see) have their
+own procedure and a `scripts/release/check_release.sh` to run before the tag:
+[docs/tags-and-releases.md](docs/tags-and-releases.md#beta-канал-pre-release).
diff --git a/docs/packaging.md b/docs/packaging.md
@@ -68,6 +68,12 @@ payload as the portable zip and AppImage.
 
 **Runtime dependencies (deb/rpm):** GTK 3, libsecret, GLib; app indicator recommended for tray.
 
+### Betas on package channels (decision, #1495)
+
+**Betas are GitHub-only.** A pre-release (`X.Y.Z-beta.N`) is published as a GitHub pre-release with its zip, AppImage, `.deb`, `.rpm`, `.flatpak` and Windows / macOS builds, and it **does not** reach AUR, the APT / DNF repository or Flathub: the Release workflow skips those jobs for it (#1492), so package users keep Stable. Someone who wants a beta on a package install downloads the zip or AppImage from the release page. The final `X.Y.Z` then reaches everyone, and a beta `.deb` / `.rpm` is versioned `X.Y.Z~beta.N` so that it upgrades to the final package (#1494).
+
+A separate beta line per package system (an APT `beta` component and a DNF `querya-beta` repository from `publish_package_repo.sh`, an AUR `querya-desktop-beta` package that conflicts with `querya-desktop`, a Flatpak `beta` branch) is **not** built. Revisit it when there is demand; `publish_package_repo.sh` would need a parameter for the component that never touches the stable index from a beta tag, and the Flatpak branch waits for the Flathub submission.
+
 ### Updater policy
 
 | Install type | In-app updater |

diff --git a/docs/release-checklist.md b/docs/release-checklist.md
@@ -4,6 +4,22 @@ Use this before tagging **`0.4.19`** or running the **Release** workflow.
 See [tags-and-releases.md](tags-and-releases.md), [CHANGELOG.md](../CHANGELOG.md).
 Manual 120 Hz DevTools QA: issue [#739](https://github.com/QueryaHub/Querya-Desktop/issues/739) (does not block this cut).
 
+## Beta release (`X.Y.Z-beta.N`)
+
+Procedure and traps: [tags-and-releases.md](tags-and-releases.md#beta-канал-pre-release).
+
+- [ ] On `release/X.Y.Z`: `scripts/release/prepare_beta.sh X.Y.Z N`, then `scripts/release/check_release.sh X.Y.Z-beta.N` passes.
+- [ ] Smoke subset on the beta build: start with an existing database, open a connection per engine, run a query, update check says *Beta*.
+- [ ] After the tag: the GitHub Release is marked **Pre-release**, is **not** *Latest* (`gh release view --json isPrerelease,isLatest`), `releases/latest` still returns the previous stable; no AUR commit, no APT / DNF update.
+- [ ] A Stable install is not offered the beta; a Beta install is.
+- [ ] **How long a beta stays out:** at least 3 days and one weekend of use; blockers are a crash on startup, data loss or corruption, a connection / query regression, a broken updater. A blocker means `beta.N+1` from the same branch.
+
+### Promote to stable
+
+- [ ] `version: X.Y.Z+B`, `## [X.Y.Z]` with the full notes, `check_release.sh X.Y.Z`, annotated tag `X.Y.Z`.
+- [ ] The release is *Latest*; AUR and the APT / DNF repositories are updated; a `.deb` / `.rpm` of the beta upgrades to the final package.
+- [ ] Beta users are offered `X.Y.Z` (a stable outranks its own beta).
+
 ## Product smoke (manual) — 0.4.19
 
 - [ ] **Buttons and controls (#1331)** — in the SQL toolbar, results bar, ERD toolbar and Preferences every control of a row has one height; hover, pressed, keyboard focus ring (Tab, not mouse click) and disabled states look the same on primary / secondary / ghost / destructive; icon buttons show a tooltip.
@@ -85,6 +101,8 @@ Verify the 0.4.4 motion tokens, smooth animations, and high refresh rate support
 
 ## Versioning and release
 
+(The items below are for the 0.4.19 cut; the versions are examples. For a beta or the stable that follows it, see *Beta release* above.)
+
 - [x] `pubspec.yaml` on the 0.4.19 track is **`0.4.19+2`** (the same as `main` after the bump that followed 0.4.18, so the merge has no version conflict).
 - [ ] After merge to `main`, confirm **Auto Version Bump** yields a **0.4.20+…** placeholder.
 - [ ] **Tag** `0.4.19` is placed on the **main merge commit that includes `0.4.19+2`** (not the auto-bump commit).

diff --git a/docs/tags-and-releases.md b/docs/tags-and-releases.md
@@ -15,10 +15,49 @@
 
 Если после merge в `main` сработал **автобамп** версии в `pubspec`, а вы поставили тег со **старым** номером (например тег `0.1.1`, а в коммите уже `0.1.2+…`), сборка **всё равно пройдёт**: имена zip возьмутся из **pubspec** (`0.1.2`), а GitHub Release останется на **вашем теге** (`0.1.1`). В логах будет предупреждение; чтобы номер тега и архивов совпадали, ставьте тег на актуальный semver из `pubspec` (например `0.1.2`).
 
+## Beta-канал (pre-release)
+
+Beta — это GitHub **pre-release** с версией вида `X.Y.Z-beta.N`. Пользователи **Stable** его не видят: приложение читает `releases/latest`, а бета никогда не становится `latest`. Пользователи, выбравшие **Beta / Early Access** (Настройки → Release channel), получают самую высокую версию из всех релизов; бета заменяется финальным релизом той же версии (`0.5.0-beta.2` < `0.5.0`). Пакетные установки (AUR, `.deb`, `.rpm`, Snap, Flatpak) получают только stable от своего менеджера пакетов.
+
+### Как выпустить бету
+
+1. Ветка `release/X.Y.Z` от `dev`.
+2. `scripts/release/prepare_beta.sh X.Y.Z N`: ставит `version: X.Y.Z-beta.N+B` в `pubspec.yaml` и секцию `## [X.Y.Z-beta.N] - <дата>` в `CHANGELOG.md` (под `## [Unreleased]`, её содержимое становится заметками беты). Ничего не коммитит.
+3. `scripts/release/check_release.sh X.Y.Z-beta.N` — проверка до тега (версия в pubspec = тег, есть секция CHANGELOG, у беты есть build number, тег свободен) и описание того, что сделает workflow.
+4. Коммит, **аннотированный** тег `X.Y.Z-beta.N` на этом коммите, `git push origin HEAD X.Y.Z-beta.N`.
+5. Workflow **Release** собирает всё и публикует **pre-release** (не `latest`), пропускает AUR и репозитории APT/DNF. В описание релиза добавляется пометка о бете. PR из `release/*` проходит job **Release branch check** (`check_release.sh`).
+
+Исправления беты: `beta.2`, `beta.3` из той же ветки тем же способом. Заметки CHANGELOG беты — дельта; финальный релиз повторяет всё.
+
+### Как повысить бету до stable (promote)
+
+Когда бета пролежала несколько дней без блокеров: в `pubspec.yaml` `version: X.Y.Z+B`, секция `## [X.Y.Z]` с **полными** заметками, `check_release.sh X.Y.Z`, аннотированный тег `X.Y.Z` (теги бет остаются). Это обычный релиз: он `latest`, уходит в AUR и APT/DNF, и пользователи Beta и Stable получают его. Пакеты беты (`X.Y.Z~beta.N`) обновляются до финального пакета.
+
+### Как откатить плохой релиз
+
+Пометьте плохой **stable** как pre-release (или удалите): `releases/latest` снова вернёт предыдущий. AUR и APT/DNF откатываются отдельно (удалить пакет из репозитория `QueryaHub/repo` / вернуть предыдущий `pkgver`).
+
+### Ловушки
+
+| Симптом | Причина | Что делать |
+|---|---|---|
+| Job **Publish GitHub Release** падает | нет секции `## [X.Y.Z-beta.N]` в `CHANGELOG.md` | `check_release.sh` называет её; добавьте до тега |
+| После merge в `main` версия беты стала `0.5.1+…` | раньше `version-bump.yml` отрезал `-beta.N` | теперь бета-версия не трогается (notice в логе); тег всё равно ставьте вручную на коммит ветки `release/*` |
+| Предупреждение `Git tag is … but pubspec semver is …` | тег и pubspec не совпадают | `check_release.sh` до тега; артефакты называются по pubspec |
+| Бета предложена Stable-пользователям | release опубликован без `prerelease` | не должно случаться (#1492); проверьте, что в версии/теге есть `-` |
+| Пакет беты «новее» финального | версия `0.5.0-beta.1` в dpkg/rpm | пакеты получают `0.5.0~beta.1` (#1494) |
+
+### Что получает каждый канал
+
+| | Stable (GitHub `latest`) | Beta / Early Access | AUR, APT/DNF, Flatpak |
+|---|---|---|---|
+| `X.Y.Z-beta.N` | нет | да | нет (бета только на GitHub, решение #1495) |
+| `X.Y.Z` | да | да | да |
+
 ## Ручной запуск (как раньше)
 
 - **Actions → Release → Run workflow** на нужном ref (обычно `main`).
-- Workflow возьмёт semver из **pubspec** на этом коммите, соберёт zip и создаст **GitHub Release** с тегом **`X.Y.Z`** (как в pubspec до `+`), если тега ещё нет.
+- Workflow возьмёт semver из **pubspec** на этом коммите, соберёт zip и создаст **GitHub Release** с тегом **`X.Y.Z`** (как в pubspec до `+`), если тега ещё нет. Если в pubspec версия с `-` (бета), релиз будет pre-release.
 
 ## Что внутри релиза