Правила увеличения номера патча в semver

Согласно semver

«Версия PATCH, когда вы делаете исправления ошибок, совместимые с предыдущими версиями».

и

«Исправление ошибки определяется как внутреннее изменение, которое исправляет неправильное поведение».

Имея это в виду, скажем, у меня есть переменная, которую можно вызвать, например, цвет. И по какой-то причине мне нужно изменить значение цвета.

v1.0.0
$color: #FFF;

v1.0.1
$color: #F0F0F0;

Теперь это переменная, которая определена в API как нечто, что могут вызывать пользователи. Я не изменил фактическую вызываемую переменную, а только возвращаемое ею значение. Для этого мне нужно внести изменения в свой код в элементе API, и я должен объединить этот код с производственной ветвью. Но действительно ли что-то подобное требует увеличения номера версии патча вашего API?


person aaronmallen    schedule 07.02.2014    source источник
comment
Вы делаете совершенно новый релиз только для этого изменения? Изменение должно быть записано в системе контроля версий, но нужно ли его распространять и выпускать только с этим? Если да, то у вас есть ответ   -  person bnjmn    schedule 07.02.2014
comment
@bnjmn что, если это единственное изменение, которое мне нужно внести в течение нескольких недель? Пользователи должны ждать обновления?   -  person aaronmallen    schedule 07.02.2014
comment
Вы меняете белый цвет на серый, и ваши пользователи не могут ждать этого обновления несколько недель, если только не произойдет что-то серьезное? Приятель, тебе серьезно нужно заполучить новых пользователей! Это меньше, чем незначительное исправление, которое может подождать...   -  person The Blue Dog    schedule 07.02.2014
comment
@PeteR цвет в данном случае является лишь примером.   -  person aaronmallen    schedule 08.02.2014


Ответы (1)


Смысл управления версиями semantic заключается в управлении зависимостями программных систем. Семантическое управление версиями обеспечивает организованную спецификацию для стандартизации этого процесса, чтобы надежно отслеживать состояние этих систем. Как указано в спецификации,

После выпуска версии пакета содержимое этой версии НЕ ДОЛЖНО изменяться. Любые модификации ДОЛЖНЫ быть выпущены как новая версия.

Если ваши изменения влияют на поведение вашего API (ввода или вывода) и требуют выпуска выпуска, то этот выпуск должен быть привязан к соответствующему номеру версии. Это позволит пользователям пакета с уверенностью полагаться на ваш пакет. Каждая версия будет вести себя так, как ожидается; не должно быть двусмысленности.


В качестве примера предположим, что вы вносите изменение и выпускаете его, но не увеличиваете номер исправления. Потенциально у вас могут быть два пользователя, которые думают, что используют один и тот же код, но получают разные значения при вызове $color API в зависимости от того, когда они приобрели v1.0.0.

Стоит отметить, что есть разные способы донести это изменение до пользователей в зависимости от того, как вы выпускаете свой пакет. Я могу представить себе два возможных случая:

  • Если исходный код пакета является общедоступным, на ранней стадии разработки пакета быстрое изменение может быть отправлено в ветку разработки, в которой пользователи могут получать изменения на свой страх и риск.
  • В качестве альтернативы, если пакет не является открытым исходным кодом, можно сделать предварительный выпуск, добавив идентификатор к версии (см. пункты 9 и 10 в спецификации).

Это всего лишь пара вариантов. Могут быть и другие в зависимости от вашей конкретной ситуации.

TL;DR Ответ

Самое главное, что после выпуска v1.0.0 v1.0.0 всегда должна вести себя одинаково. Какими бы тривиальными ни были эти изменения, они все равно остаются изменениями. Это касается всех версий, X.Y.Z.

person bnjmn    schedule 07.02.2014
comment
Во-вторых: как насчет изменений в документации API, таких как README.md, следует ли увеличивать semver и для этих типов изменений? - person aaronmallen; 10.02.2014
comment
@aaronmallen Если это просто изменение, которое вы вносите в свой репозиторий, то нет. Однако, если вы упаковываете эти изменения (независимо от того, что упаковка означает для вашего проекта), вы ДОЛЖНЫ увеличить номер версии (см. пункт 3 в спецификации). - person deadly; 04.06.2014
comment
@deadly, значит, номер версии напрямую не связан с самим исходным кодом (то есть с репозиторием), а только с пакетом? - person aaronmallen; 05.06.2014
comment
@aaronmallen Точно. Вам нужно только выбрать номер версии, когда вы делаете выпуск. - person deadly; 05.06.2014