Стандарт change package

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

• Статус документа: living standard
• Актуально на: 1 апреля 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении release workflow, ownership-модели, handoff-процесса или документационного стандарта
• Область применения: обязательный процесс упаковки, проверки, документирования и передачи изменений
• Связанные документы:
• Инженерные принципы
• Стандарт документации
• Project change log
• Модель stage delivery и release handoff

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

Этот документ фиксирует, как в 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.

Для frontend-facing package

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

• запись в 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 — для каждого завершённого change package;
• project/execution-checkpoints.md — если пакет меняет статус этапа или чекпоинта.

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

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

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;
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.