Версионирование и выпуск продукта¶
Требования применяются к запускаемым и публикуемым компонентам проекта.
Версия стандартов регулируется отдельно по STD-MAN-002. Уровни
обязательности определены в корневом README.md.
DEV-REL-001. Единый источник версии компонента¶
Уровень: MUST
Применяется к: каждому release или deployment компонента
Компонент должен иметь один машинно-читаемый источник release-идентификатора.
Идентификатор должен однозначно сопоставляться с Git commit и неизменяемым
идентификатором артефакта по DEV-BUILD-003. Для container image это MAY быть
digest или уникальный непереиспользуемый release tag. Повторная сборка другого
содержимого не должна публиковаться под уже использованным идентификатором.
Формат MAY быть SemVer, номером store build, календарной версией или commit-based release, если правила сравнения и уникальности определены проектом.
Обоснование¶
Версия полезна только тогда, когда однозначно называет проверенное содержимое, а не произвольную строку deployment.
Проверка¶
- сопоставление version source, Git tag или release и artifact identifier;
- контролируемая попытка повторной публикации другого содержимого;
- чтение версии из собранного компонента.
Исключения¶
Внутренний непрерывно поставляемый сервис MAY использовать полный commit SHA как release-идентификатор без отдельного Git tag.
DEV-REL-002. Контракт service.version¶
Уровень: MUST
Применяется к: компоненту, публикующему telemetry с service.version
service.version должен формироваться из release-идентификатора
DEV-REL-001, встраиваться или передаваться pipeline поставки и совпадать во
всех сигналах одного развёрнутого артефакта. Значение не должно вычисляться из
текущей ветки, mutable tag, времени запуска или содержимого рабочей копии.
Для mobile-артефакта с составным идентификатором service.version должен
содержать публичную версию, а app.build_number — монотонный номер сборки по
MOB-BUILD-002. Пара этих полей должна однозначно сопоставляться с commit и
артефактом.
Одновременно работающие артефакты должны различаться значением
service.version либо, для mobile, парой service.version и
app.build_number, позволяющей разделять их SLI, ошибки и диагностику.
Обоснование¶
Единая версия связывает наблюдаемый отказ с точным артефактом при rollout и rollback.
Проверка¶
- сравнение telemetry с metadata артефакта и deployment;
- тест двух одновременно работающих артефактов;
- для mobile — сопоставление пары
service.versionиapp.build_numberс metadata store-артефакта; - проверка неизменности значения после restart.
Исключения¶
Не допускаются для production telemetry.
DEV-REL-003. Схема публичного версионирования¶
Уровень: SHOULD
Применяется к: публичному SDK, CLI, package или другому продукту, для которого потребитель выбирает версию
Проекту следует использовать Semantic Versioning с документированным
определением публичного контракта: MAJOR для несовместимого изменения,
MINOR для обратно совместимой возможности и PATCH для обратно совместимого
исправления.
Если экосистема требует другую схему, проекту следует определить эквивалентные правила совместимости, порядок сравнения, prerelease и момент стабилизации контракта.
Обоснование¶
Потребитель должен понимать совместимость обновления до его установки.
Проверка¶
- contract-diff относительно предыдущего release;
- сопоставление категории изменения и новой версии;
- тест порядка stable и prerelease версий.
Исключения¶
Версионирование store-приложения или платформенного package MAY следовать обязательной схеме целевой экосистемы.
DEV-REL-004. Release notes для потребителя¶
Уровень: MUST
Применяется к: release, который изменяет используемый внешним потребителем контракт, поведение, требования к эксплуатации или security-свойство
Вместе с release должны публиковаться версионируемые notes, содержащие
идентификатор версии, дату, добавленные возможности, исправления, несовместимые
изменения, deprecations, security-значимые изменения и необходимые действия
потребителя. Раздел без изменений MAY отсутствовать; существенное изменение не
должно скрываться в общей категории other.
Notes должны ссылаться на migration guide, когда обновление требует изменения кода, конфигурации или данных потребителя.
Обоснование¶
Артефакт сообщает, что изменилось технически, но не позволяет потребителю оценить действие и риск обновления.
Проверка¶
- сопоставление contract и behavior diff с notes;
- проверка ссылки на migration guide;
- публикация notes в том же release object.
Исключения¶
Внутренний deployment без отдельного потребительского выбора версии MAY использовать автоматически сформированный журнал изменений, если несовместимость регулируется отдельным rollout-контрактом.
DEV-REL-005. Уведомление об устаревании¶
Уровень: MUST
Применяется к: планируемому удалению или несовместимому изменению публичного либо межкомандного контракта
До удаления проект должен опубликовать deprecation notice с идентификатором контракта, затронутыми версиями, причиной, заменой или migration path, каналом поддержки, версией первого предупреждения и самой ранней версией либо датой удаления.
Notice должен доставляться через канал, доступный известным потребителям, и оставаться доступным в release notes и документации до завершения миграции. Фактическое удаление должно проверять выполненные сроки и состояние известных потребителей.
Обоснование¶
Маркер deprecated в коде не уведомляет владельца работающей интеграции и не задаёт конечный срок поддержки.
Проверка¶
- contract-тест deprecated marker или warning;
- проверка публикации notice и списка известных потребителей;
- release gate для минимального срока и migration status.
Исключения¶
Немедленное отключение уязвимого контракта выполняется по OPS-INC-003 и
должно сопровождаться доступным уведомлением после стабилизации.