Версионирование

Версии важны.

Аккуратное ведение версий важно по нескольким причинам:

  • обеспечение совместимости и прослеживаемости появления новых функций в приложении и API;
  • документирование функциональных возможностей со ссылкой на конкретную версию в которой эти возможности появились;
  • обозначение текущего статуса готовности программного продукта (pre-release, alpha, beta);
  • планирования новой функциональности (road map).

Номер версий

Традиционно версия состоит из нескольких цифр разделяемых точкой.

Чаще всего для нумерации используется шаблон из трех частей: X.Y.Z (major.minor.patch).

Правила нумерации:

  • major изменяется в случае существенных изменений нарушающих обратную совместимость;
  • minor изменяется при расширении функциональности, добавлении новых методов в API;
  • patch изменяется внесении исправлений и несущественных улучшений в существующую функциональность.

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

Удобнее всего при нумерации версий придерживаться правил семантического версионирования.

Semantic versioning (aka SemVer) is a widely-adopted version scheme that uses a three-part version number (Major.Minor.Patch), an optional pre-release tag, and an optional build meta tag.

Семантическое версионирование допускает использования нуля в качестве major номера версии, что является исключением из общей системы правил и вносит много несогласованности. Настоятельно рекомендуется избегать этого и начинать нумерацию с версии 1.0.0, ну или использовать 0.Y.Z для внутренней разработки и публиковаться в открытый доступ уже с номером 1.0.0-alpha.

Для удобства можно использовать четвертую составляющую номера версии (major.minor.patch.build) как сквозной номер сборки который увеличивается на единицу при каждой новой сборке программы.

Схема версионирования

Версии в разработке
 1.0.0-1
 1.0.0-2
 1.0.0-3
 ...

Альфа версия
 1.0.0-alpha.1
...

Бета версия
 1.0.0-beta.1
...

Предрелизные версия
 1.0.0-rc.1
...

Финальная версия
 1.0.0

Версии в API

Добавление в API номера версии позволит в будущем при развитии приложения обеспечить безшовный переход на новую версию API. Например добавление номера версии в URL REST API даст возможность поддерживать одновременно две версии, если это потребуется.