Политика инженерии релизов

Пять политик определяют, как выпускаются релизы apothem.

1. Семантическое версионированиеCopy Anchor Link

Проект поставляется в соответствии с семантическим версионированием 2.0. Номера версий имеют вид MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD].

Теги кандидатов используют формат vX.Y.Z-rc.N (кандидат в релиз) или vX.Y.Z-alpha.N / vX.Y.Z-beta.N (ранний доступ).

2. Теги релизовCopy Anchor Link

Каждый релиз помещает в main подписанный git-тег вида vMAJOR.MINOR.PATCH. Тег запускает .github/workflows/release.yml, который собирает, подписывает, генерирует SBOM и происхождение SLSA-3 и публикует страницу GitHub Release.

Соглашения по тегам:

• Формат — ровно vMAJOR.MINOR.PATCH. Без префикса release- и без суффикса -final.
• Аннотация — каждый тег является аннотированным (git tag -a -s) и несёт сводку примечаний к релизу в сообщении тега.
• Подпись — каждый тег подписан GPG. Рабочий процесс релиза дополнительно создаёт бесключевую подпись Sigstore cosign для каждого артефакта и запись о происхождении SLSA-3; обе прикрепляются к странице GitHub Release.

Модель релизов: аддитивнаяCopy Anchor Link

Релизы аддитивны. Каждый релиз добавляет один коммит в main и один тег; main никогда не отправляется через force-push, и ни один опубликованный тег, GitHub Release или версия npm не удаляется, не перемещается и не используется повторно. Каждый релиз сохраняет свой тег, свой GitHub Release и свою версию npm, и все они остаются опубликованными. Версии npm неизменяемы: опубликованный name@version никогда не может быть заменён, а номер, публикация которого была отозвана, никогда не может быть использован повторно. Закреплённые установки и воспроизводимые сборки зависят от каждого опубликованного тега. Руководства по циклу релиза и восстановлению релиза оба следуют этой модели.

Правило фасада релиза репозитория (раздел «Release Facade» инструкций для участников) излагает эту модель. Его требование показывать только текущую версию, отражённое в правиле freshness-facade, относится к тому, что говорят публичные поверхности. Оно не ограничивает, какие релизы остаются опубликованными.

3. Политика устареванияCopy Anchor Link

Текущая линия публичной поддержки — последняя выпущенная минорная версия. Когда у проекта несколько публичных минорных версий, матрица поддерживаемых версий в SECURITY.md является источником истины для любых дополнительных окон поддержки только критических исправлений.

Ритм устаревания:

• Объявление — устаревший символ или поведение объявляется в разделе ### Deprecated файла CHANGELOG.md того релиза, в котором появляется устаревание. Примечания к релизу отражают объявление об устаревании.
• Окно отсрочки — устаревшие символы остаются доступными в течение как минимум одного полного минорного цикла до удаления.
• Удаление — удаление происходит при повышении MAJOR. Каждый удалённый символ несёт строку ### Removed в CHANGELOG.md и запись руководства по миграции в разделе Практические руководства.

Минимальные версии сред выполненияCopy Anchor Link

Apothem объявляет две минимальные версии сред выполнения: requires-python = ">=3.10" в pyproject.toml и "engines": {"node": ">=18"} в package.json.

• Каждая объявленная минимальная версия тестируется. Минимальная версия Python выполняется в матрице CI quality и в рабочем процессе CI Matrix. Рабочий процесс npm Shim запускает npm-шим на минимальной версии Node и на каждой более поздней мажорной LTS-версии: он проверяет ошибку об отсутствующем предварительном требовании, node bin/apothem.mjs --version, пробную установку в изолированном домашнем каталоге и упакованный tarball через npx. Среда выполнения, которая не тестируется, не объявляется.
• Окончание срока поддержки раскрывается. Когда среда выполнения, которая всё ещё является объявленной минимальной версией, достигает окончания срока поддержки в upstream, это сообщает руководство по установке, называя версии, которым следует отдавать предпочтение. Срок поддержки Python 3.10 закончился 2026-10-01; Node.js 18 и 20 — 2025-04-30 и 2026-04-30. Все три остаются поддерживаемыми минимальными версиями.
• Повышение минимальной версии — это устаревание. Оно следует ритму, описанному выше: объявление в ### Deprecated, как минимум один полный минорный цикл, в течение которого старая минимальная версия продолжает тестироваться, затем релиз, который её повышает, фиксирует изменение. requires-python, engines.node, проверки версий в установщиках и матрицы CI меняются вместе в этом релизе.

4. Политика несовместимых измененийCopy Anchor Link

Несовместимые изменения требуют:

1. Тикета RFC — открытого с меткой тикета rfcs, описывающего несовместимое изменение, путь миграции и стратегию отката.
2. 30-дневного окна для комментариев — RFC остаётся открытым не менее 30 дней до слияния. Сопровождающие могут продлить окно, когда это оправдано обратной связью.
3. Повышения MAJOR — релиз, вносящий несовместимое изменение, повышает компонент MAJOR.
4. Руководства по миграции — изменение поставляется с записью в Практических руководствах, которая проводит оператора через миграцию.

5. Политика откатаCopy Anchor Link

Если релиз демонстрирует регрессию, блокирующую внедрение:

1. Отмена — проблемные коммиты отменяются в main.
2. Релиз с исправлением вперёд — последующий релиз выходит как vMAJOR.MINOR.PATCH+1, неся отмену плюс любые инкрементальные исправления. Предыдущий плохой релиз не удаляется из GitHub Releases, а его версия npm остаётся опубликованной (версии npm неизменяемы) и помечается с помощью npm deprecate. Аннотация ### Yanked в CHANGELOG.md документирует ситуацию, чтобы воспроизводимые сборки оставались привязанными.
3. Коммуникация — откат сопровождается уведомлением security-advisories (когда это относится к безопасности) или закреплённым для инцидента тикетом GitHub (когда это относится к надёжности).

См. такжеCopy Anchor Link

• CHANGELOG.md — канонический реестр релизов.
• SECURITY.md — матрица поддерживаемых версий и каналы сообщений.
• cicd-pipeline.md — классы CI-проверок, которые контролируют каждый релиз.
• deployment-checklist.md — проверка готовности к продакшну для каждого релиза.