Запрещенные изменения в коде или продолжение истории ремонта одного крана

[Deosis]

Если коротко, то:

• Написать новый метод.
• Старый метод пометить @deprecated и оставить в нем только передачу управления в новый.

Также в устаревших методах стоит писать в какой версии они будут удалены.
ПС:

Изменение типа принимаемых аргументов методом

Изменение типа возвращаемого значения методом

Статья слезно просит дописать её.

[maghamed]

Ну не совсем настолько коротко :)
Так как основная идея была все же про рефакторинг. И что даже строгие ограничение BC не должны ему мешать.

Также в устаревших методах стоит писать в какой версии они будут удалены.

А вот здесь немножко не так. Мы не можем знать заранее в какой версии они будут удалены, так как наши планы могут поменяться, мы можем только знать с какой версии они перестали быть актуальны.
Поэтому чтобы проинформировать сторонних разработчиков о наших планах по изменению публичного кода мы добавляем маркер since вместе с аннотацией @deprecated

Как в примере:

/**
 * @deprecated since 2.1.0
 * @see \Magento\Framework\Model\ResourceModel\Db\AbstractDb::save()
 */
public function save()
{
    // ...
}

Данный маркер должен выставляться также не мануально программистом, который пишет код, так как и он может не знать в какой именно релиз попадет его код. А автоматической тулой, которая делает предпелизную сборку. Таким образом инструмент сборки проставит since для нового кода, который должен быть поставлен в текущий релиз.

Статья слезно просит дописать её.

Дописал эти два пункта

[vintage]

А какая программисту разница с какой версии добавился депрекейшен? Ему важно надо ли всё бросать и рефакторить код под новый апи иначе завтра у него всё сломается, или может расслабиться и запланировать рефакторинг на после релиза. Поэтому лучше всего писать ориентировочную дату до которой апи будет точно поддерживаться.

[maghamed]

Нет, не лучше. Что значит ориентировочную дату? Это значит ваши даты релизов должны быть и в коде тоже. А что если вы не успеете по каким-то причинам и релиз отложится? Все даты в коде станут неактуальны.
Программисту достаточно знать с какой версии изменения стали deprecated. Для того чтобы сторонний программист начал готовиться заранее и перестал использовать deprecated апи в новом коде и тем самым перестал накапливать технический долг, который должен будет в любом случае исправлен позже. Для всего остального есть SemVer — и при апгрейде на следующий мажорный релиз программист будет видеть список обратно несовместимых изменений, которые были сделаны для того чтобы оценить что именно ему нужно сделать для поддержки своего кода в новой версии.

[vintage]

А что если вы не успеете по каким-то причинам и релиз отложится? Все даты в коде станут неактуальны.

И что? Главное, чтобы ломающие изменения не были выплеснуты раньше времени. А опоздать можно хоть навсегда.

для всего остального есть SemVer

Вы это Ангуляру скажите, у которого есть есть версии 1.*, где минорные версии ломают обратную совместимость, и есть 2, 4, 5, 6 по расписанию.

[unreacheble]

созданию задач (user story) на рефакторинг, которые не имеют business value для product owner-a, а соответственно такие задачи не будут попадать в топ продуктового беклога

Я конечно же понял о чём речь. Но всё-же такая дикая связка русского с английским читается со смехом :)
Определитесь с языком. ;)

[maghamed]

это Agile терминология, которая получила широкое распространение и стала устоявшимся термином, а терминология может использоваться как есть (As is если пожелаете).

Вас же не смущает использования других терминов как deprecated, cohesion и т.д.