# Стандарт change package

## Паспорт документа

- Статус документа: living standard
- Актуально на: 1 апреля 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при изменении release workflow, ownership-модели, handoff-процесса или документационного стандарта
- Область применения: обязательный процесс упаковки, проверки, документирования и передачи изменений
- Связанные документы:
- [Инженерные принципы](./engineering-principles.md)
- [Стандарт документации](./documentation-standard.md)
- [Project change log](../project/project-change-log.md)
- [Модель stage delivery и release handoff](../operations/stage-delivery-model.md)

## Цель документа

Этот документ фиксирует, как в Qadam должен выглядеть change package. Его задача — сделать каждое значимое изменение воспроизводимым, проверяемым и передаваемым другой команде без устных пояснений.

## 1. Что считается change package

Change package — это не просто коммит. Это законченный пакет изменений, который:

- решает одну осмысленную задачу;
- имеет понятные границы;
- проходит релевантные проверки;
- оставляет после себя обновлённый код, документы, checkpoints и changelog.

## 2. Обязательные поля change package

Каждый нетривиальный change package обязан иметь:

1. `Package ID`
2. `Scope`
3. `Затронутые репозитории`
4. `Затронутые сервисы`
5. `Проверки`
6. `Документационные обновления`
7. `Rollback note`
8. `Checkpoint impact`
9. `Frontend impact`, если применимо
10. `Security impact`, если пакет затрагивает auth, permissions, uploads, secrets, proxy, rate limiting или миграции с чувствительными данными

## 2.1. Язык commit message

Текст commit message в проекте должен быть на русском языке.

Допустимый формат:

- `feat(api): переведён upload на S3-compatible storage`
- `fix(auth): синхронизирован JWT guard с async AuthService`
- `docs(roadmap): checkpoints приведены к текущему status`

Правило:

- допускается использовать латинские `type/scope` в стиле conventional commits;
- основная смысловая часть commit message должна быть написана по-русски;
- commit message должен описывать результат уже выполненного пакета, а не намерение что-то сделать;
- предпочтительная форма: результативная, например `добавлен`, `исправлен`, `стабилизирован`, `синхронизированы`, `вынесен`, `переведён`;
- технические термины, имена сервисов, файлов, API и библиотек допускается оставлять в оригинале;
- это правило применяется и к squash merge commit message, если пакет попадает в `main`.

## 3. Формат идентификаторов

Рекомендуемые префиксы:

- `CORE-YYYY-MM-DD-NN` — backend/platform package
- `OPS-YYYY-MM-DD-NN` — infra/runtime package
- `DOCS-YYYY-MM-DD-NN` — documentation/governance package
- `FE-BE-YYYY-MM-DD-NN` — frontend-facing contract package

Один и тот же пакет не должен менять ID по ходу работы.

## 4. Минимальный состав артефактов

### Для backend/platform package

- код в `qadam-core`;
- релевантные тесты;
- если есть API change — обновлённый OpenAPI artifact;
- обновлённые канонические docs;
- запись в [project-change-log.md](../project/project-change-log.md).

### Для frontend-facing package

Дополнительно обязательно:

- запись в [frontend-change-log.md](../frontend/frontend-change-log.md);
- явная пометка, требует ли запись действий от frontend на roadmap-портале;
- явная migration note для frontend-команды;
- указание, требуется ли обновление `qadam-web/openapi/openapi.json`.

### Для ops/runtime package

Дополнительно обязательно:

- обновление `deployment-runbook.md`;
- обновление `environment-matrix.md`, если меняются env/secrets/boundaries;
- обновление `current-state.md`, если поменялся фактический production runtime.
- если пакет меняет quality/review workflow, обновление `.gitea/workflows/*` и PR review-шаблона.

## 5. Обязательные документальные обновления

### Всегда обновлять

- [project/project-change-log.md](../project/project-change-log.md) — для каждого завершённого change package;
- [project/execution-checkpoints.md](../project/execution-checkpoints.md) — если пакет меняет статус этапа или чекпоинта.

### Обновлять по условию

- [project/current-state.md](../project/current-state.md) — если изменился production/runtime;
- [project/roadmap.md](../project/roadmap.md) — если поменялась последовательность этапов;
- [architecture/api-routes.md](../architecture/api-routes.md) — если поменялся API behavior;
- [frontend/frontend-change-log.md](../frontend/frontend-change-log.md) — если пакет затрагивает frontend-команду;
- [operations/deployment-runbook.md](../operations/deployment-runbook.md) — если поменялся deploy/rollback/runtime контур;
- [operations/environment-matrix.md](../operations/environment-matrix.md) — если поменялись env или access boundaries;
- [specs/qadam-platform/*](../../specs/qadam-platform/implementation.md) — если пакет меняет согласованное платформенное решение.

## 6. Обязательные проверки

Проверки выбираются по типу пакета, но релевантный minimum gate обязателен:

- `pnpm check-types`
- `pnpm test`
- `pnpm build`
- `pnpm export:openapi`, если меняется API
- `pnpm check:api-contract`, если пакет затрагивает frontend contract
- `pnpm check:docs`, если пакет меняет канонические документы
- post-deploy smoke, если пакет уже выкатывается на production

Если для репозитория существует обязательный workflow quality gate, merge-ready change package обязан проходить и его. Для `qadam-core` таким gate является `.gitea/workflows/quality-gate.yml`.

## 6.1. Обязательный PR review и security gate

Каждый нетривиальный пакет должен проходить не только build/test, но и review discipline.

Минимум обязателен такой:

- change оформляется через PR или PR-совместимый review package;
- используется `.gitea/PULL_REQUEST_TEMPLATE.md`;
- reviewer получает явный `risk summary`, `rollback note` и `checkpoint impact`;
- для auth/token/cookie/session, permissions/roles/guards, uploads/files, secrets/env, proxy/rate-limit и Prisma migrations обязателен отдельный security impact review.

## 7. Порядок жизни change package

1. Зафиксировать `Package ID` и scope.
2. Подготовить commit message на русском языке в результативной форме.
3. Изменить код и тесты.
4. Обновить релевантные документы.
5. Обновить checkpoints и changelog.
6. Прогнать проверки.
7. Пройти PR review/security gate.
8. Если пакет требует согласованного frontend/backend релиза, дождаться подтверждения readiness второй стороны и merge в `main`.
9. Только после этого считать пакет завершённым.

## 7.1. Правило для stage release

Для текущего проекта каноническая release-модель такая:

- change packages готовятся на текущем сервере и в локальных репозиториях;
- stage deploy живёт на отдельном сервере и забирает согласованные изменения из `main` внешним автоматическим контуром;
- локальный ручной deploy с этой машины не считается обязательным этапом каждого package, если цель пакета — staged UI verification после merge.

Это означает:

- merge-ready package должен быть готов к попаданию в `main`, а не к ручному `systemctl restart` на этой машине;
- если пакет влияет на frontend, backend-команда обязана сначала оформить handoff, а не просто “доделать код”;
- если frontend и backend должны выйти согласованно, релизным действием считается согласованный merge в `main`, а не локальный smoke в изоляции.

## 8. Правило по checkpoints и changelog

- `project/execution-checkpoints.md` — отвечает на вопрос, в каком состоянии находится поэтапная реализация проекта.
- `project/project-change-log.md` — отвечает на вопрос, какие пакеты изменений уже реально прошли через проект.

Нельзя обновлять только одно из этих двух мест, если change package меняет ход реализации проекта.

## 9. Правило по frontend-команде

Если пакет добавляет новый endpoint, меняет старый endpoint, response shape, auth behavior или любой другой frontend-значимый контракт:

1. обновить `OpenAPI`;
2. обновить [frontend/frontend-change-log.md](../frontend/frontend-change-log.md);
3. явно отметить `Frontend impact` в change package;
4. если пакет требует действий от frontend, он должен появиться в frontend-блоке на `qadam-roadmap.2fab.app`;
5. не считать пакет завершённым до выполнения этих действий.

## 10. Что запрещено

- Делать production change без `Package ID`.
- Закрывать пакет без записи в `project-change-log.md`.
- Менять статус этапа без обновления `execution-checkpoints.md`.
- Публиковать frontend-impact package без записи в `frontend-change-log.md`.
- Оставлять docs update “на потом” для уже выкатившегося change package.
- Мержить нетривиальный пакет без прохождения обязательного repo-side quality gate, если такой gate уже существует.
- Публиковать auth/security-sensitive change без явного security impact review.