Изучение семантического версионирования

  • 4 мин

Одним из преимуществ управления версиями является использование семантического управления версиями (SemVer).

Семантическая версия не является стандартным, но предлагает согласованный способ выражения намерения и семантики конкретной версии.

Она описывает версию, обеспечивающую обратную совместимость с предыдущими версиями.

Семантический формат версий

Семантическое версионирование использует номер версии с тремя частями и необязательную метку.

Формат Major.Minor.Patch

Версия имеет форму Major.Minor.Patch , которая соответствует трем типам изменений, описанных в предыдущем разделе.

Структура версии:

  • Основной: Первое число указывает на необратимые изменения.
  • Несовершеннолетний: Второй номер указывает новые функции (обратная совместимость).
  • Патч: Третье число указывает на исправления ошибок (обратная совместимость).

Примеры версий с помощью схемы семантического управления версиями:

  • 1.0.0 — первоначальный стабильный релиз
  • 3.7.129 — версия 3 с большим количеством дополнительных обновлений и исправлений
  • 2.0.0 — основная версия 2 с критическими изменениями

У этих версий нет меток.

Правила увеличения версий

Когда следует увеличить каждое число:

Увеличение основной версии (X.0.0)

  • Критические изменения: Внесите несовместимые изменения API.
  • Удаление функциональных возможностей: Удаление устаревших функций.
  • Изменения архитектуры: Фундаментальный редизайн.

Example:

  • 1.5.3 2.0.0→ при появлении критических изменений

Минорное увеличение (x.Y.0)

  • Новые возможности: Добавление функций в обратно совместимом режиме.
  • Нерекомендуемая функция: Пометьте функции как устаревшие (но по-прежнему функциональные).
  • Усовершенствования: Существенные улучшения существующих функций.

Example:

  • 1.5.3 → 1.6.0 при добавлении новых функций

Инкрементный патч (x.y.Z)

  • Исправления ошибок: Исправление ошибок с обратной совместимостью.
  • Исправления безопасности: Исправлены уязвимости системы безопасности.
  • Улучшения производительности: Незначительные оптимизации производительности.

Example:

  • 1.5.3 → 1.5.4 для исправления багов и ошибок

Предварительные версии

Для предварительной версии обычно используется метка после обычного номера версии.

Формат метки

Метка — это текстовый суффикс, разделенный дефисом от остальной части номера версии.

Сама метка может быть любым текстом, описывающим характер предварительной версии.

Структура меток:

Major.Minor.Patch-label

Распространенные метки предварительной версии

Примеры включают rc1, beta27, и alpha, формируя номера версий, например:

  • 1.0.0-alpha — ранняя версия разработки, неустойчивая.
  • 1.0.0-beta — Функционал завершён, но потенциально содержит ошибки.
  • 1.0.0-beta.2 — вторая бета-версия.
  • 1.0.0-rc1 — Кандидат на релиз, возможно готовый для релиза.
  • 1.0.0-preview — предварительная версия для ранних отзывов.

Пример прогрессии версий:

1.0.0-alpha.1
1.0.0-alpha.2
1.0.0-beta.1
1.0.0-beta.2
1.0.0-rc1
1.0.0-rc2
1.0.0

Соглашения о метках для предварительного выпуска

Общие префиксы меток:

  • альфа: Очень ранняя версия, возможны ошибки и кардинальные изменения.
  • Бета-версия: Функция завершена, проходит тестирование.
  • rc (кандидат выпуска): Потенциально окончательная версия, последняя стадия тестирования.
  • Предварительный просмотр: Предварительная версия для отзывов.
  • dev: Снимок разработки.

Числовые суффиксы:

Метки часто включают числа для последовательных предварительных версий.

  • 1.0.0-beta.1 1.0.0-beta.2 → →1.0.0-beta.3

Использование предварительных версий

Предварительные выпуски — это распространенный способ подготовки к выпуску версии пакета без меток.

Преимущества предварительных выпусков

Ранние отзывы:

Ранние пользователи могут использовать зависимость от предварительной версии для сборки с помощью нового пакета.

  • Тестовая интеграция: Проверка работы пакета с существующими системами.
  • Сообщить о проблемах: Найдите ошибки до официального выпуска.
  • Предоставьте отзыв: Предложить улучшения или изменения.

Постепенное развертывание:

  • Промежуточный выпуск: Сначала выпустите для небольшой аудитории.
  • Устранение рисков: Выявление проблем до широкого выпуска.
  • Доверие: Создайте уверенность в стабильности.

Предварительные предостережения

Как правило, использование предварительной версии пакетов и их компонентов для выпущенного программного обеспечения не является хорошей идеей.

Риски использования предварительных выпусков в рабочей среде:

  • Неустойчивость: Предварительные версии могут иметь неокрытые ошибки.
  • Критические изменения: Будущие предварительные версии могут ввести критические изменения.
  • Нет гарантий: Нет гарантий обратной совместимости.
  • Ограничения поддержки: Ограничена или не поддерживается предварительная версия.

Тестирование предварительных версий

Хорошо ожидать влияния новых компонентов, создав отдельную ветвь в базе кода и используя предварительную версию пакета.

Лучшие практики по тестированию предварительных версий.

  • Отдельная ветвь: Создайте ветвь компонентов для тестирования.
  • Изолированная среда: Тестирование в непроизводственных средах.
  • Мониторинг поведения: Следите за непредвиденным поведением или проблемами с производительностью.
  • Проблемы с документом: Отслеживайте обнаруженные проблемы.

Есть вероятность, что будут несовместимые изменения от предварительной версии к окончательной версии.

Метаданные и сведения о сборке

SemVer 2.0 также поддерживает метаданные сборки, добавляемые знаком плюса:

1.0.0-beta.1+20231015.abc123

Метаданные сборки:

  • Не учитывается в приоритете версий: Две версии, отличающиеся только в метаданных сборки, считаются равными.
  • Сведения: Полезно для отслеживания номеров сборки и хэшей коммитов.
  • Пример:1.0.0+build.123 или 1.0.0-beta+exp.sha.5114f85

Приоритет версий

SemVer определяет четкие правила приоритета версий:

Правила сравнения

  1. Сравнение основных, дополнительных, исправлений: В этом порядке числово.
  2. Предварительные версии: Всегда имеет более низкий приоритет, чем связанная обычная версия.
  3. Сравнение меток: Буквенно-цифровые сегменты сравниваются лексически, числовые сегменты сравниваются числовым образом.

Примеры в порядке (наименьшее до самого высокого):

1.0.0-alpha
1.0.0-alpha.1
1.0.0-alpha.beta
1.0.0-beta
1.0.0-beta.2
1.0.0-beta.11
1.0.0-rc.1
1.0.0
1.0.1
1.1.0
2.0.0

Преимущества семантического управления версиями

Четкое общение:

  • Намерение: Номер версии четко сообщает о характере изменений.
  • Совместимость: Легко определить, является ли обновление безопасным.
  • Предсказуемость: Согласованное управление версиями в разных пакетах.

Автоматическое управление зависимостями:

  • Ограничения версий: Менеджеры пакетов могут автоматически управлять версиями.
  • Безопасные обновления: Средства могут безопасно обновляться до совместимых версий.
  • Разрешение конфликтов: Проще разрешать конфликты зависимостей.

Внедрение экосистемы:

  • Отраслевый стандарт: Широко распространено во многих экосистемах.
  • Поддержка инструментов: Руководители пакетов понимают SemVer.
  • Ожидания сообщества: Разработчики ожидают соответствия SemVer.

Семантическое управление версиями в Артефактах Azure

Артефакты Azure поддерживают семантику управления версиями для всех типов пакетов:

  • NuGet: Поддержка Native SemVer 2.0.
  • npm: SemVer является стандартом.
  • Maven: Совместим с принципами SemVer.
  • Пайтон: PEP 440 совместим с концепциями семантического версионирования.
  • Универсальные пакеты: Использует SemVer 2.0.

Представления ленты данных и SemVer:

  • представление @Prerelease: Автоматически включает версии с метками.
  • Вид @Release: Включает только версии без меток.
  • представление @Local: Отображает все версии независимо от метки.

Реализация семантического управления версиями

Ручное управление версиями:

  • Обновление файлов пакета: Обновление версии вручную в package.json, .nuspecи т. д.
  • Коммит с тегом: Присвойте коммиту номер версии в виде тега.

Автоматическое управление версиями:

# Using npm version command
npm version patch  # Increment patch: 1.0.0 -> 1.0.1
npm version minor  # Increment minor: 1.0.1 -> 1.1.0
npm version major  # Increment major: 1.1.0 -> 2.0.0

# With prerelease
npm version prerelease --preid=beta  # 1.0.0 -> 1.0.1-beta.0

В конвейерах CI/CD:

# Azure Pipelines example
- task: GitVersion@5
  inputs:
    runtime: "core"
    configFilePath: "GitVersion.yml"

- script: |
    echo "Semantic Version: $(GitVersion.SemVer)"
    echo "NuGet Version: $(GitVersion.NuGetVersion)"
  displayName: "Display version"

См. также Семантическое версионирование 2.0.0.