Как объявить обратные несовместимые изменения в проекте OSS?

Question

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

Поэтому возникает вопрос: как объявить будущие обратно несовместимые изменения в проекте FLOSS (с открытым исходным кодом) , чтобы пользователи могли подготовиться к ним и либо изменить свое использование, либо настроить программу на использование старого поведения .

Поскольку это проект OSS, он упакован различными дистрибутивами независимо и может обновляться автоматически без вмешательства пользователя. И тогда обратное несовместимое изменение может испортить рабочий процесс некоторых пользователей (например, сторонние скрипты).

Направления, которые в настоящее время рассматриваются (и используются):

• список рассылки проекта
• Домашняя страница проекта
• примечания к выпуску (сначала предупреждение, затем объявление)
• Блог сопровождающего

Редактировать 1: Это (обратно несовместимое) изменение может произойти в некоторых основных выпусках.

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

Редактировать 2: В переходный период конфигурация по умолчанию (которая должна быть изменена на отказ / отклонение по умолчанию) изменяется на warn , с описанием, как повернуть предупреждение, которое также защитит от обратной несовместимости изменений в поведении по умолчанию.

Но если это автоматизированная система, которая может не помочь ...

---

Рассматриваемый проект Git , распределенная система управления версиями;
см. Раннее предупреждение пользователей в журнале Гитстера (блог Junio ​​C Hamano)

Answer 1

• Изменить основной номер версии
• Объявите об этом всеми доступными вам способами
• Добавить заметное объявление в readme
• Добавить код, который преобразует между старым и новым, если требуется БД или другие изменения
• Добавить код, который обнаруживает использование устаревших методов, хранилище данных и т. Д. И предупреждает пользователя перед выполнением разрушительных изменений
• Задайте соответствующие вопросы типа FAQ на основных веб-сайтах Q / A, поэтому, когда у людей есть вопросы, ответ будет немедленным и очевидным с помощью простого поиска

Но основной номер версии является основной целью - люди ожидают, что переходы с 1.x на 2.x вызовут проблемы, и будут более осторожны при обновлении.

-Adam

Answer 2

У вас есть хорошие ответы о том, как вывести слово. Но миграция моего собственного мышления является самой большой проблемой для меня, особенно когда устаревшие функции находятся в моей мышечной памяти. Отучиться сложнее, чем учиться.

Получение предупреждений о несовместимости , когда я на самом деле использую команды, которые собираются изменить особенно полезно, особенно с изменениями по умолчанию. Что-то вроде:

 $ git foo  
 Note: git foo currently defaults to HEAD. Starting with
 version 2.0, git foo will instead default to master.

Answer 3

Все вышеперечисленное плюс.

Если у вас есть изменение, где:

Точный синтаксис неразрушающей команды изменится на разрушительную команду

Я не вижу другого выбора, кроме как сделать изменение вместо этого more , чтобы сделать старую команду совершенно недействительной, чтобы, если пользователь обновляет и пытается (или, возможно, пытается скрипт), команду старого стиля, он завершается описательное сообщение об ошибке на stderr. Использование stderr для предупреждающих сообщений о командах с тонкими (или не очень тонкими) изменениями, которые не являются деструктивными, также является хорошей идеей. Определение деструктивного является несколько более сложным в исходном хранилище

Использование предупреждений stderr для простых методов устаревания часто хорошо, но некоторые люди будут жаловаться, что это нарушает их (плохо написанные) сценарии. В этих случаях тихая версия об устаревании (все неинвазивные формы устаревания), за которой следует устная версия (предупреждения stderr), за которой, возможно (см. Ниже), с не функциональным, но текущим выпуском, за которым следует полное удаление. Этот последний нефункциональный выпуск будет сильно зависеть от рассматриваемого проекта, поскольку он может доставить больше хлопот, чем стоит, особенно тем пользователям, которые хорошо себя ведут и постоянно следят за устаревшей функциональностью.

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

Примечание для кода , а не изменений на уровне сценария, во многих современных языках можно оставить в заглушках методов с атрибутами / аннотациями, которые будут полностью скрывать их от intellisense, а также отказываться от компиляции против них. Это делает их присутствие (с простым исключением, если используется) гораздо более приятным способом выяснить, что вы не можете их использовать, чем исключение MissingMethodException во время выполнения или что-то еще.

Answer 4

Я мог бы перейти на RSS (если существует), Twitter (если существует), список рассылки (по крайней мере, 3 раза по мере того, как обновление закрывается), домашнюю страницу (сделать ее очень контрастной, чтобы ее было легко увидеть) и блог , конечно. Примечания к выпуску почти не читаются, поэтому воспринимайте это как последний пункт информации.

(я опубликовал это как первый ответ, но не появился)

Answer 5

Только мои 0,02 доллара. Современные среды разработки (в частности, .NET) предоставляют средства для сообщения разработчику о том, что определенные API объявлены устаревшими / устаревшими и будут удалены в будущих версиях. Компилятор Microsoft C / C ++ имеет # устаревшую прагму .

Если ничего из этого не поддерживается в вашей среде, положитесь на управление версиями , чтобы предоставить обратную связь от Compat.