--- title: Ведите Changelog description: Не позволяйте друзьям сливать логи гита в CHANGELOG language: ru version: 0.3.0 --- %h1= current_page.data.title %h2= current_page.data.description Version #{current_page.metadata[:page][:version]} :markdown ### Что такое лог изменений? Лог изменений – это файл, который содержит поддерживаемый, упорядоченный в хронологическом порядке список значимых изменений для каждой версии проекта с открытым исходным кодом. 
#{File.read("CHANGELOG.md")}
:markdown ### Для чего нужен лог изменений? Чтобы пользователи и контрибьюторы могли с меньшими усилиями точно определить, какие значимые изменения были сделаны в каждом релизе (или версии) проекта. ### Почему я вообще должен думать об этом? Потому, что инструменты программирования делаются для людей. Если вам пофигу, зачем вы вообще занимаетесь программным обеспечением с открытым исходным кодом? У вас обязательно в голове должен быть центр «не пофигу» :) Я [беседовал с Адамом Стаковиаком и с Джеродом Санто в подкасте The Changelog][thechangelog] (в тему название, правда?) о том почему авторам программного обеспечения с открытым исходным кодом и их коллегам должно быть не пофигу, и о моих мотивах в создании этого проекта. Послушайте, если у вас есть время (1:06). ### Что должно быть в хорошем логе изменений? Я рад, что вы спросили. Хороший лог изменений придерживается этих приниципов: - Он сделан для людей, а не машин, так что понятность имеет решающее значение. - Легко сослаться на любой раздел (поэтому Markdown лучше обычного текста). - Один подраздел на каждую версию. - Релизы перечислены в обратном хронологическом порядке (самые новые – сверху). - Пишите все даты в формате `YYYY-MM-DD`. (Например: `2012-06-02` для даты `2 июня 2012`.) Он международный, [рациональный](https://xkcd.com/1179/), и независим от языка. - Ясно указывает, использует ли проект [Семантическое Версионирование][semver]. - Каждая версия должна: - Показывать дату релиза в формате, упомянутом выше. - Группировать изменения согласно их влиянию на проект следующим образом: - `Added` для новых функций. - `Changed` для изменений в существующей функциональности. - `Deprecated` для функциональности, которая будет удалена в следующих версиях. - `Removed` для функциональности, которая удалена в этой версии. - `Fixed` для любых исправлений. - `Security` для обновлений безопасности. ### Как минимизировать время, необходимое для ведения лога изменений? Всегда ведите секцию `Unreleased` в начале файла, чтобы держать в ней не выпущенные изменения. Это нужно для двух вещей: - Люди смогут видеть, какие изменения ожидаются в ближайших релизах - В момент релиза вам нужно всего лишь заменить секцию `Unreleased` на номер версии и добавить новую секцию `Unreleased` в начале файла. ### Что заставляет плакать единорогов? Хорошо… давайте разберёмся. - **Выгрузка изменений лога коммитов.** Просто не делайте так, это никому не принесёт пользы. - **Отсутствие отметок планируемой к удалению функциональности.** Когда люди обновляются от одной версии к другой, им должно быть очевидно до боли, что сломается. - **Даты в местном формате.** В Соединённых Штатах, люди сначала пишут месяц («06-02-2012» для даты 2 июня 2012, что не имеет *никакого* смысла), хотя много людей в остальном мире пишет роботоподобное «2 июня 2012», всё ещё произнося это по-другому. «2012-06-02» логично работает от самого большого к самому маленькому, не пересекается с другими форматами дат, и является [стандартом ISO](http://www.iso.org/iso/home/standards/iso8601.htm). Таким образом, этот формат является рекомендуемым для логов изменений. Существуют и другие. Помогите мне собрать слёзы единорогов, [открыв тикет][issues] или пулл-реквест. ### Существует стандарт формата лога изменений? К сожалению, нет. Спокойней. Я знаю, что вы яростно бросились на поиски ссылки на GNU-руководства по стилю лога изменений, или на поиски файла «guideline» с парой параграфов в GNU NEWS. GNU-руководство по стилю неплохо для начала, но оно наивно. В наивности нет ничего плохого, но когда людям нужно руководство, она редко бывает полезна. Особенно, когда приходиться сталкиваться со множеством краевых случаев. Этот проект [содержит информацию, которая, я надеюсь, станет соглашением получше о ведении файлов CHANGELOG][CHANGELOG] для всех проектов с открытым исходным кодом. Может ли сообщество учиться на своих ошибках, а не просто действовать согласно десяти записям, которые были написаны много лет назал, и, якобы, без одной ошибки? Хорошо. Поэтому, пожалуйста, посмотрите вокруг, и помните, что [обсуждения и предложения по улучшению приветствуются][issues]! ### Как можно назвать файл лога изменений? Ну, если вы не не можете ответить на этот вопрос, глядя на пример выше, `CHANGELOG.md` пока наилучший вариант. Некоторые проекты используют `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, и так далее. Это непорядок. Все эти имена только усложняют поиск нужного файла. ### Почему люди не могут использовать просто дифф команды `git log`? Потому, что диффы логов по своей природе содержат слишком много «шума». С их помощью невозможно сделать подходящий лог изменений даже в гипотетическом проекте, который делается идеальными программистами, которые никогда не делают опечаток, никогда не забывают коммитить новые файлы, никогда не пропускают ни одну часть рефакторинга. Назначение коммита в том, чтобы задокументировать один атомарный шаг в процессе развития кода от одного состояния к другому. Назначение лога изменений – документировать значимые различия между этими состояниями. Как отличаются хорошие комментарии к коду и сам код, также отличаются друг от друга и лог изменений с логом коммитов: первые отвечают на вопрос *почему*, а вторые на вопрос как. ### Могут ли логи изменений быть автоматически распарсены? Это сложно из-за того, что люди следуют сильно отличающимся форматам и соглашениям о именах файлов. Гем для Руби [Vandamme][vandamme], который создали в команде [Gemnasium][gemnasium], парсит многие (но не все) логи изменений проектов с открытым исходным кодом. ### Почему вы пишите то «CHANGELOG», то «лог изменений»? «CHANGELOG» – это имя файла. Оно несколько крикливо, но это историческое соглашение, которому следуют многие проекты с открытым исходным кодом. В качестве примеров подобных файлов можно привести [`README`][README], [`LICENSE`][LICENSE], и [`CONTRIBUTING`][CONTRIBUTING]. Верхний регистр в имени файла (который в старых операционных системах заставляет эти файлы находиться наверху списков) используется для привлечения внимания. Так как в этих файлах содержится важная метаинформация о проекте, они могут быть полезны любому использующему или дорабатывющему проект, также как [бейджи проектов с открытым исходным кодом][shields]. Когда я упоминаю «лог изменений», я говорою о назначении этого файла: об учёте изменений. ### Как насчёт yanked-релизов? Yanked-релизы – это версии, которые изымаются из обращения из-за серьёзного бага или проблемы безопасности в них. Часто такие версии даже не упоминаются в логах изменений. А должны. И вот как вам следует их упоминать: `## [0.0.5] - 2014-12-13 [YANKED]` Тег `[YANKED]` такой «громкий» не просто так. Очень важно, чтобы люди его заметили. А из-за того, что он окружён скобками, его легче определить программно. ### Стоит ли переписывать лог изменений? Конечно. Всегда есть причины для улучшения лога изменений. Я регулярно открываю пулл-реквесты в проекты с открытым исходным кодом с неподдерживаемыми логами изменений для добавления недостающих релизов. Также вы можете обнаружить что вы забыли адресовать критичное изменение в описании версии. В этом случае очевидно, что нужно обновить лог изменений. ### Как я могу помочь? Этот документ **не истина в последней инстанции**; это моё тщательно сформулированное мнение вместе с информацией и примерами, которые я собрал. Хотя я предоставил настоящий [CHANGELOG][] из [GitHub-репозитария][gh], я специально избегал цели создать *стандарт* или чёткий список правил (как это делает, например, [SemVer.org][semver]). Я сделал это потому, что хочу, чтобы наше сообщество достигло консенсуса. Я верю, что дискуссия также важна, как и её результат. Так что, пожалуйста, [**участвуйте**][gh]. [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CHANGELOG.md [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/README.md [gemnasium]: https://gemnasium.com/ [gh]: https://github.com/olivierlacan/keep-a-changelog [issues]: https://github.com/olivierlacan/keep-a-changelog/issues [semver]: https://semver.org/ [shields]: https://shields.io/ [thechangelog]: https://changelog.com/podcast/127 [vandamme]: https://github.com/tech-angels/vandamme/