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

Question

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

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

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

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

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

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

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

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

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

---

Проект, о котором идет речь, является Мерзавец, распределенная система контроля версий;
видишь Предоставление раннего предупреждения пользователям в дневник гитстера (Блог Джунио Си Хамано)

Answer 1

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

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

-Адам

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

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

(Я опубликовал это в качестве первого ответа, но не появился)

Answer 4

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

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

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

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

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

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

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

Answer 5

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

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