Это зависит исключительно от того, какие гарантии стабильности вы дали своим пользователям, и какую боль вы хотите причинить своим пользователям.
В идеале ваш API использует semver, так что любое критическое изменение приводит к увеличению номера основной версии. На практике желательно делать это практически никогда. Если ваш API установлен через некоторый менеджер пакетов, вы можете захотеть создать новое имя пакета после критического изменения, чтобы простое обновление не вызывало конфликтов (например, myapi2 v2.123.4
vs myapi3 v3.2.1
). Это может быть ненужным, если ваш менеджер пакетов поддерживает более жесткие зависимости версий (например, спецификация зависимостей ~v2.120
не включает в себя v3.*
), но у разных имен пакетов есть преимущество, заключающееся в том, что несовместимые версии могут очень легко использоваться рядом. Даже при использовании semver может быть целесообразно иметь период амортизации.
Семвер не всегда применим. Тогда важнее сообщить четкую политику стабильности. Например:
- Экспериментальные функции могут быть удалены без предварительного уведомления.
- Функции могут быть удалены в целях безопасности в любое время.
- Другие функции будут только удалены
- ... после того, как устарела в выпущенной версии
- … Где этой версии не менее трех месяцев
- ... и будет отмечен удар в основной версии.
Такие политики работают особенно хорошо, когда у вас есть регулярные выпуски, поэтому существует четкий период устаревания, например, один год.
Помимо пометки каких-либо частей API как устаревших, вы должны сделать это устаревание широко известным. Например:
- Есть раздел в вашем списке изменений о будущих направлениях и амортизации.
- Передайте свое намерение осудить до того, как вы начнете осуждение, и послушайте сообщество, чтобы увидеть, есть ли существенные возражения.
- Сообщите, какие выгоды принесут эти изменения. В зависимости от вашей пользовательской базы, подходящими носителями могут быть информационные бюллетени, презентации, сообщения в блогах или пресс-релизы. Спиннируя «мы создаем потрясающую новую функцию! (что требует удаления этой широко используемой старой функции) »немного меньше разочаровывает, чем удаление функции без контекста.
Что касается точного периода выбытия, сначала посмотрите, должны ли вы соблюдать какие-либо контракты на поддержку с вашими пользователями. Такие контракты могут потребовать от вас сохранения совместимости в течение некоторого периода. Если нет, рассмотрите любое последующее воздействие. Попробуйте изменить менее быстро, чем нижестоящие пользователи, чтобы они могли самостоятельно пройти цикл устаревания. Нижестоящим пользователям потребуется некоторое время, чтобы адаптироваться к вашим изменениям, поэтому у вас никогда не должно быть периода устаревания меньше месяца.