==================================================================================================== https://keepachangelog.com/ru/1.0.0/
Что такое лог изменений? Лог изменений – это файл, который содержит поддерживаемый, хронологически упорядоченный список изменений для каждой версии проекта.
Зачем вести лог изменений? Чтобы пользователям и контрибьюторам было проще точно понять, какие изменения были сделаны в каждом релизе (или версии) проекта
Кому нужен лог изменений? Людям. Будь то клиенты или разработчики, конечные пользователи программного обеспечения это люди, и им важно, с чем они работают. Когда программное обеспечение меняется, люди хотят знать почему и что изменилось.
Как мне сделать хороший лог изменений? Главные принципы Лог изменений ведётся для людей, не для машин. Для каждой версии должен быть отдельный раздел. Одинаковые типы изменений должны быть сгруппированы. Должна быть возможность поставить ссылку на любую версию или раздел. Последняя версия должна идти в начале файла. У каждой версии указана дата выпуска. Уточните, следуете ли вы принципам Семантического версионирования Типы изменений Добавлено для новых функций. Изменено для изменений в существующей функциональности. Устарело для функций, которые скоро будут удалены. Удалено для удалённых функций. Исправлено для любых исправлений. Безопасность в случае уязвимостей. Как мне тратить меньше усилий на ведение лога изменений? Ведите раздел Новое с изменениями для новой версии в начале файла.
Это нужно для двух вещей:
Люди смогут видеть, каких изменений им ожидать в ближайших релизах В момент релиза вы можете переместить изменения раздела Новое в раздел нового релиза. Бывают плохие логи изменений? Да. Вот несколько способов чтобы сделать их не такими полезными.
Диффы лога коммитов Использование диффов лога коммитов это плохая идея: они очень шумные. Шумят мердж-коммиты, коммиты с непонятными названиями, изменения в документации и тому подобное.
Назначение коммита в том, чтобы задокументировать шаг в эволюции исходного кода. В некоторых проектах следят за историей коммитов, в некоторых нет.
Назначение же раздела в логе изменений — задокументировать ключевые различия, часто между несколькими коммитами, чтобы ясно донести их назначение до конечных пользователей.
Игнорирование устаревающих функций Когда люди обновляются с одной версии на другую, должно быть до боли очевидно, что сломается. Должна быть возможность обновиться до версии, которая перечисляет устаревающие функции, удалить устаревшие данные, затем обновиться до версии, в которой устаревающие функции становятся удалёнными.
Если вы не ведёте лог изменений, то хотя бы указывайте в нём устаревающие и удалённые функции, а также все критичные изменения.
Непонятные даты В США сначала пишут месяц (06-02-2012 для 2 июня 2012), в то время как большинство людей в остальном мире пишут роботоподобное 2 июня 2012, произнося эту дата по-разному. Запись 2012-06-02 логично идёт от большего к меньшему, не пересекается с большинством других форматов дат, и является стандартом ISO. Поэтому именно такой формат рекомендуется для логов изменений.
Есть и другие. Помогите мне собрать эти антипаттерны, создав тикет или пулл-реквест. Часто задаваемые вопросы Существует ли стандарт формата логов изменений? Как назвать файл лога изменений? Что насчёт функции "Релизы" на Гитхабе? Могут ли логи изменений быть автоматически распарсены? Что насчёт yanked-релизов? Имеет ли смысл переписывать лог изменений? Как я могу помочь вашему проекту? Обсуждения Я приходил в подкаст The Changelog, чтобы поговорить о том, почему мейнтейнеры и контрьбьюторы должны вести логи изменений, а также о моей мотивации к созданию этого проекта.