From 3334ee38c19a14b77e3d4ed7e61a627a48a9730b Mon Sep 17 00:00:00 2001 From: ZhuchkaTriplesix Date: Sun, 18 Oct 2026 11:12:28 +0300 Subject: [PATCH] docs(release): Beta channel procedure, promote and rollback, the traps; betas are GitHub-only on package channels (#1496, #1495) --- CONTRIBUTING.md | 5 ++++- docs/packaging.md | 6 ++++++ docs/release-checklist.md | 18 +++++++++++++++++ docs/tags-and-releases.md | 41 ++++++++++++++++++++++++++++++++++++++- 4 files changed, 68 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d87df081..5800e16d 100644 --- 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 index fe675889..90165b7c 100644 --- 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 index 0cdadc7f..db161745 100644 --- 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 index 50a01a8b..395010f1 100644 --- 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. ## Что внутри релиза