Проект Keep a CHANGELOG направлен на стандартизацию лучших практик ведения журналов изменений

Журнал изменений — это самый быстрый и удобный способ для пользователей и участников определить существенные изменения в проекте при переходе от одной версии к другой. Журнал существует для информирования пользователей.

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

Оливье Лакан , инженер-программист в Code School , создал сайт и соответствующий репозиторий GitHub под названием Keep a CHANGELOG с обширной коллекцией рекомендаций по написанию лучших журналов изменений.

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

Один полезный совет, который предлагает Лакан, который обычно не встречается даже в самых лучших, созданных вручную CHANGELOG, — это рекомендация держать раздел «Неизданные» вверху. Это помогает пользователям отслеживать потенциальные изменения для предстоящих выпусков. Ведение раздела «Unreleased» сводит к минимуму усилия по написанию журналов во время выпуска, поскольку вы можете легко добавить номер версии в раздел по мере добавления изменений и создать новый заголовок Unreleased.

Программные инструменты для людей

Лакан приводит веские доводы в пользу приоритетности создания журнала изменений для вашего проекта с открытым исходным кодом:

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

Он надеется, что проект Keep a CHANGELOG поможет сформировать лучшее соглашение о файлах CHANGELOG для всех проектов с открытым исходным кодом. Обсуждения и предложения приветствуются в очереди задач репозитория проекта на GitHub. Авторы уже зарегистрировали более двух десятков соображений.

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