docs: staging as manual QA snapshot after local tests

Staging is not auto-synced with main; testers report against fixed X.Y.Z on the stand.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: AHTu21

.github/pull_request_template.md

@@ -7,7 +7,7 @@
 - [ ] Фича (в `main` после merge поднимется MINOR/PATCH автоматически)
 - [ ] Исправление
 - [ ] Только docs / CI (версия может не измениться)
-- [ ] Продвижение на тест: PR **`main` → `staging`** (версию не дублируем, см. docs/WORKFLOW.md)
+- [ ] Продвижение на тест: PR **`main` → `staging`** (после локального build/smoke; на стенде фиксируется версия `X.Y.Z` для QA)
 
 ## Чеклист
 

CHANGELOG.md

@@ -25,7 +25,7 @@
 ### Разработка
 
 - **Версии:** после merge в `main` CI поднимает **2-ю или 3-ю** цифру по правилам [docs/VERSIONING.md](./docs/VERSIONING.md); прод (**1-я** цифра) — [docs/ADMIN.md](./docs/ADMIN.md).
-- **Процесс:** CI на PR, защита `main`/`staging`, тест через ветку `staging` — [docs/WORKFLOW.md](./docs/WORKFLOW.md), [docs/GITHUB_BRANCH_PROTECTION.md](./docs/GITHUB_BRANCH_PROTECTION.md).
+- **Процесс:** CI на PR, защита `main`/`staging`; на тест — только осознанный срез `main` → `staging` после локальных проверок (стабильная версия для тестировщиков) — [docs/WORKFLOW.md](./docs/WORKFLOW.md), [docs/GITHUB_BRANCH_PROTECTION.md](./docs/GITHUB_BRANCH_PROTECTION.md).
 
 ### API и сервер
 

docs/ADMIN.md

@@ -39,7 +39,7 @@
 
 ### Тестовый стенд (`staging`)
 
-Перед продом выкладывайте сборку с ветки **`staging`**, обновляя её PR **`main` → `staging`** ([WORKFLOW.md](./WORKFLOW.md)). Версия на стенде = версия в `main` (уже поднятая ботом 2/3 цифры). Отдельного bump на `staging` нет.
+Не каждый merge в `main` сразу на стенде. Выкладка только когда на `main` прошли **локальные** build/smoke, затем PR **`main` → `staging`** — на стенде одна **стабильная** версия `X.Y.Z` для отчётов тестировщиков. Подробно: [WORKFLOW.md](./WORKFLOW.md). Прод — только после QA на стенде.
 
 ### Позже (когда дойдёте)
 

docs/GITHUB_BRANCH_PROTECTION.md

@@ -1,57 +1,80 @@
-# Настройка защиты веток на GitHub (один раз)
+# Настройка защиты веток на GitHub
 
-Владелец репозитория: **Settings → Rules → Rulesets** (или **Branches → Branch protection rules**).
+Владелец репозитория: **https://github.com/AHTu21/retrogen** → **Settings**.
 
-## Ветка `main`
+Ниже — пошагово. Сначала **`main`**, затем **`staging`**.
 
-**Цель:** код только через PR, конфликты решены до merge, сборка зелёная.
+---
+
+## 1. Ветка `main` (интеграция)
+
+**Settings** → **Rules** → **Rulesets** → **New branch ruleset** (или *Branch protection rules* → Add rule).
+
+| Поле | Значение |
+|------|----------|
+| Ruleset name | `Protect main` |
+| Enforcement | Active |
+| Target branches | Include default branch **`main`** |
 
-Рекомендуемые правила:
+**Branch rules** — включить:
 
-| Правило | Значение |
-|---------|----------|
-| Branch name pattern | `main` |
-| Restrict deletions | включить |
-| Require a pull request before merging | включить |
-| Required approvals | `0` или `1` (на ваш выбор) |
-| Dismiss stale approvals | по желанию |
-| Require status checks to pass | включить |
-| Required check | **`build`** (workflow CI) |
-| Require branches to be up to date | **включить** — перед merge нужен `git merge main` / Update branch |
-| Do not allow bypassing | включить для всех, кроме админа при необходимости |
-| Restrict pushes | никто не пушит напрямую в `main` (только merge PR) |
+- [x] **Restrict deletions**
+- [x] **Require a pull request before merging**
+  - Required approvals: **0** (или 1, если хотите обязательное ревью)
+  - [x] Require approval of the most recent reviewable push (если approvals ≥ 1)
+- [x] **Require status checks to pass**
+  - Add checks: выберите **`build`** (job из workflow **CI**)
+  - [x] Require branches to be up to date before merging
+- [x] **Block force pushes**
+- [x] **Restrict pushes** (только merge через PR; прямой push в `main` запрещён)
 
-После сохранения: прямой `git push origin main` будет отклонён; только merge PR.
+**Save**.
+
+Проверка: `git push origin main` с локального коммита должен быть **отклонён** (если не admin bypass).
 
 ---
 
-## Ветка `staging`
+## 2. Ветка `staging` (тестовый стенд)
+
+Отдельный ruleset **`Protect staging`**:
+
+| Поле | Значение |
+|------|----------|
+| Target branches | Include by pattern: **`staging`** |
 
-**Цель:** на тест попадает только осознанный снимок с `main`.
+**Branch rules:**
+
+- [x] **Require a pull request before merging**
+- [x] **Require status checks to pass** → **`build`**
+- [x] **Block force pushes**
+- [x] **Restrict pushes** (фичи не в `staging` напрямую)
+
+**Договорённость в команде** (GitHub не всегда ограничивает base/head):
+
+- PR на `staging` только **`main` → `staging`**
+- Не merge в `staging` «на бегу» с каждой фичей — только после [чеклиста в WORKFLOW.md](./WORKFLOW.md)
+
+Ветка `staging` уже есть на remote. Обновляется **только** merge такого PR.
+
+---
 
-| Правило | Значение |
-|---------|----------|
-| Branch name pattern | `staging` |
-| Require pull request | включить |
-| Allowed merge sources | только из `main` (если доступно в ruleset) или договорённость: PR только `main` → `staging` |
-| Require status checks | **`build`** на PR в `staging` |
-| Restrict pushes | не пушить фичи напрямую в `staging` |
+## 3. Labels (опционально, 1 мин)
 
-Создать ветку (если ещё нет), один раз с локальной `main`:
+**Issues** → **Labels** → New:
 
-```bash
-git checkout main
-git pull
-git checkout -b staging
-git push -u origin staging
-```
+| Label | Цвет | Смысл |
+|-------|------|--------|
+| `version:minor` | | принудительно minor bump на main |
+| `version:patch` | | принудительно patch |
+| `version:skip` | | не менять версию |
+| `qa-request` | | просьба выкатить на стенд после локальных тестов |
 
 ---
 
-## Проверка
+## 4. Проверка
 
-1. Создайте тестовую ветку, PR в `main` — должен запуститься **Actions → CI**.
-2. Пока CI не зелёный — merge недоступен (если включены checks).
-3. Смоделируйте конфликт — кнопка Merge должна быть заблокирована до resolve.
+1. Ветка `test/rules` → PR в `main` → должен запуститься **Actions → CI**.
+2. Пока CI красный — merge в `main` недоступен (если checks включены).
+3. Сконфликтующий PR — кнопка merge заблокирована до **Resolve conflicts**.
 
-Подробный процесс: [WORKFLOW.md](./WORKFLOW.md).
+Процесс выкладки на стенд: [WORKFLOW.md](./WORKFLOW.md).

docs/VERSIONING.md

@@ -8,7 +8,7 @@
 | **2-я (MINOR)** | Крупное обновление в **`main`** | **Автоматически** при merge в `main`, если merge «большой» |
 | **3-я (PATCH)** | Небольшое обновление в **`main`** | **Автоматически** при merge в `main`, если merge «малый» |
 
-Ветка **`staging`** (тестовый стенд) **не меняет** версию повторно — на стенде та же цифра, что в `main` после PR `main` → `staging`. См. [WORKFLOW.md](./WORKFLOW.md).
+Ветка **`staging`** **не поднимает** версию отдельно: на стенде фиксируется уже существующий номер с `main` (например `0.7.3`) в момент **осознанного** PR `main` → `staging` после локальных тестов. Тестировщики ссылаются на этот номер в отчётах. См. [WORKFLOW.md](./WORKFLOW.md).
 
 Отображение в UI: поле `version` в **`client/package.json`** (окно «О программе»).
 

docs/WORKFLOW.md

@@ -1,85 +1,106 @@
 # Совместная разработка: ветки, PR, конфликты, тест, прод
 
-## Ветки
+## Три уровня, не один срез
 
-| Ветка | Назначение | Версия (2–3 цифры) | Деплой |
-|--------|------------|-------------------|--------|
-| **`main`** | Интеграция: сюда вливаются фичи через PR | **Авто** после merge ([VERSIONING.md](./VERSIONING.md)) | Локально / dev |
-| **`staging`** | Тестовый стенд: только проверенный снимок с `main` | **Та же**, что в `main` (повторно не bump) | Тестовый сервер |
-| **Тег / прод** | Внешний стабильный срез | **1-я цифра** вручную ([ADMIN.md](./ADMIN.md)) | Прод |
+| Уровень | Ветка / срез | Для кого | Как обновляется |
+|---------|----------------|----------|-----------------|
+| **Интеграция** | `main` | Разработчики | Каждая фича через PR; версия 2/3 цифры **растёт автоматически** после merge |
+| **Тестовый стенд** | `staging` | Тестировщики, отчёты о багах | **Только вручную**, после **локальных** проверок; на стенде **одна зафиксированная** версия `X.Y.Z` |
+| **Прод** | тег / релиз | Пользователи «во вне» | Вручную, 1-я цифра — [ADMIN.md](./ADMIN.md) |
 
 ```text
-feature/* ──PR──► main ──(+бот chore(version))──► PR ──► staging ──► тест-стенд
-                      │                                              │
-                      └──────────────────────────────────────────────┘
-                                    позже: прод (ADMIN)
+feature/* ──PR──► main ──(бот: версия 0.7.3)──►  локально: build + smoke
+                                                      │
+                                    «готовы к QA»     ▼
+                              PR main → staging ──► деплой стенда
+                              (версия на стенде = 0.7.3)
+                                                      │
+                                              позже: прод
 ```
 
+**`staging` не копия `main` в реальном времени.** Пока вы не сделали PR «выкладка на тест», на стенде остаётся **прошлый** стабильный снимок — тестировщики не ловят «полуфабрикат» с только что влитой фичей.
+
 ---
 
-## Обычный день (фича)
+## Обычная разработка (только `main`)
 
 1. `git checkout main && git pull`
-2. `git checkout -b feature/краткое-имя`
-3. Код, коммиты, push ветки
-4. GitHub → **Pull request → `main`**
-5. Ждёте **CI (build)** — зелёная галочка
-6. Если **«This branch has conflicts»** — конфликт **до** merge (см. ниже)
-7. Ревью → **Merge**
-8. Бот (если нужно) коммитит `chore(version): bump to v…` в `main`
-9. У партнёра: `git pull origin main`
+2. `git checkout -b feature/краткое-имя` → код → push
+3. **Pull request → `main`**, дождаться зелёного **CI (build)**
+4. При **conflicts** — merge недоступен, правите локально → push (см. ниже)
+5. **Merge** → бот может добавить `chore(version): bump to v…`
+6. Партнёр: `git pull origin main`
 
-**В `staging` и на тест ничего само не попадает** — только когда создадите PR `main` → `staging`.
+На тестовый стенд это **не** попадает автоматически.
 
 ---
 
-## Вывод на тестовый стенд
+## Выкладка на тестовый стенд (осознанный срез)
 
-Когда `main` готов к проверке на стенде:
+Делайте, когда на **`main`** уже есть нужная версия (например `0.7.3`) и вы **локально** убедились, что сборка ок.
 
-1. PR **`main` → `staging`** (база `staging`, head `main`)
-2. Разрешить конфликты, если есть (редко, если `staging` регулярно обновлять)
-3. Merge → деплой с ветки **`staging`** (настройка сервера — [DEPLOYMENT.md](./DEPLOYMENT.md))
-4. Версия на стенде = версия в `main` (из «О программе» / `package.json`)
+### Чеклист перед PR на `staging`
 
-Отдельного bump версии при merge в `staging` **нет** — иначе тест и интеграция разъедутся.
+- [ ] `git checkout main && git pull` (включая коммит `chore(version)`, если был)
+- [ ] `npm ci` (или `npm install`)
+- [ ] `npm run build` без ошибок
+- [ ] `npm run dev` — smoke: вход, комната, ключевые сценарии фичи
+- [ ] Миграции: `npm run db:deploy` на **тестовой** БД стенда (не на прод)
+- [ ] В PR указать версию: **«Promote v0.7.3 to staging for QA»**
 
----
+### PR на стенд
+
+1. GitHub → **New pull request**: base **`staging`**, compare **`main`**
+2. Описание для тестировщиков: что проверять, известные ограничения
+3. **CI (build)** зелёный, конфликтов нет → **Merge**
+4. Деплой с ветки **`staging`** на тест-сервер ([DEPLOYMENT.md](./DEPLOYMENT.md))
+5. **Сообщение тестировщикам** (чат / issue), например:
 
-## Конфликты: когда и как
+   > Стенд обновлён. Версия для отчётов: **0.7.3** (О программе → номер версии).  
+   > В баге указывайте: версию, браузер, шаги.
 
-| Этап | Что видите | Что делать |
-|------|------------|------------|
-| PR в `main` | GitHub: **Can’t merge**, conflicts | Локально: `git checkout feature/…`, `git merge main`, правка `<<<<`, `git push` |
-| PR `main` → `staging` | То же | `git checkout staging`, `git pull`, `git merge main` в PR-ветку или в `staging` по инструкции GitHub |
-| После merge | Нет «тихих» конфликтов в git | — |
-| Доска Retrogen (409) | Два редактора одной комнаты | Логика приложения, не git |
+### Фиксация версии для отчётов (рекомендуется)
 
-**Защита ветки** (см. [GITHUB_BRANCH_PROTECTION.md](./GITHUB_BRANCH_PROTECTION.md)):
+После merge PR в `staging`, на коммите стенда:
 
-- в `main` нельзя merge с конфликтами (GitHub не даст кнопку);
-- можно требовать **актуальную ветку** (`main` обновлён перед merge) и **зелёный CI**.
+```bash
+git checkout staging && git pull
+VER=$(node -p "require('./package.json').version")
+git tag -a "qa/v${VER}" -m "QA build on staging"
+git push origin "qa/v${VER}"
+```
+
+Тег **`qa/v0.7.3`** — точная точка в git, если нужно воспроизвести баг. Номер для людей — тот же **`0.7.3`** в UI.
 
-Автоматически конфликты **не решаются** — только показываются; исправление и новый push — **вы**.
+Повторная выкладка на тот же стенд без смены версии на `main` не нужна; новая выкладка — когда на `main` уже **0.7.4** и снова прошли локальные тесты.
 
 ---
 
-## Что автоматизировано, что нет
+## Конфликты
+
+| Этап | Действие |
+|------|----------|
+| PR в `main` | GitHub блокирует merge → `git merge main` в feature-ветку, правка, push |
+| PR `main` → `staging` | То же; base — **текущий** `staging`, head — **main** |
+| Доска (409) | Не git — логика приложения |
+
+Защита веток: [GITHUB_BRANCH_PROTECTION.md](./GITHUB_BRANCH_PROTECTION.md).
+
+---
+
+## Автоматизация
 
 | Действие | Авто? |
 |----------|--------|
-| Сборка на PR (CI) | Да |
-| Блок merge при конфликте | Да (GitHub + настройки) |
-| Bump 2/3 цифры после merge в `main` | Да |
-| Push в `main` без PR | Нет (если включена защита) |
-| Обновление `staging` | Нет — PR вручную |
-| Прод (1-я цифра) | Нет — [ADMIN.md](./ADMIN.md) |
-| CHANGELOG | Нет — вручную / `npm run changelog:append` |
+| CI на PR в `main` / `staging` | Да |
+| Bump версии при merge в `main` | Да |
+| Обновление `staging` | **Нет** — только PR после локальных тестов |
+| Тег `qa/v…` | Вручную (рекомендуется) |
+| Прод | [ADMIN.md](./ADMIN.md) |
 
 ---
 
-## Labels (GitHub)
-
-`version:minor`, `version:patch`, `version:skip` — для бота версий.
+## Labels
 
-Опционально: `ready-for-staging` на PR в `main`, когда готовы к выкладке на тест после merge.
+- `version:minor` / `version:patch` / `version:skip` — бот версий на **main**
+- `qa-request` (создайте сами) — PR в `main` готов к выкладке на стенд после merge