Перевод статьи «A Beginner’s Guide to Git — What is a Changelog and How to Generate it».
Итак, вы — разработчик и хотите использовать Git для одного из своих проектов. При этом вы хотите сообщать пользователям вашего приложения об осуществленных вами изменениях, но не знаете, как это сделать. Данная статья поможет вам в этом.
Мы рассмотрим, что такое changelog, а также познакомимся с двумя способами его создания — простым и более сложным.
Что такое changelog?
Changelog это файл, в котором содержится хронологически упорядоченный список изменений, внесенных в проект. Он часто создается на основе версий ПО — с указанием дат их выхода и списками добавленных, исправленных и удаленных функций.
«Журнализация изменений проекта (англ. changelog) представляет собой программное протоколирование изменений, вносимых в большой проект. Обычно записи журнала изменений содержат информацию об исправлении ошибок, о новых возможностях и т.д.», — Википедия.
В целом, есть два способа вести changelog:
- простой — создать текстовый файл и начать перечислять в нем все вносимые изменения с указанием дат;
- «программистский» (или ленивый) — автоматически генерировать changelog из сообщений коммитов.
Мы остановимся на втором способе.
Зачем нужен changelog?
Я думаю, вы задаетесь вопросом, зачем вообще нужен этот changelog и почему вам стоит потратить время на его создание.
Changelog это как бы краткое содержание всех изменений, которые вы внесли в проект. Список этих изменений должен быть понятен как пользователям, так и другим разработчикам, работающим с вашим проектом.
В нашем очень быстро меняющемся мире пользователи должны знать, изменилось ли что-то на сайте или в приложении, которыми они пользуются.
Разработчикам, работающим над крупным проектом, может быть интересно, как этот проект развивается.
Если вы работаете над проектом с открытым кодом, вы можете найти файл CHANGELOG.md в GitHub-репозитории. Этот файл информирует контрибьюторов о последних обновлениях проекта.
Где можно найти changelog-и?
Changelog-и встречаются повсюду! Они могут принимать разные формы и располагаться в разных местах, но они есть буквально в каждом проекте.
Вот краткий список мест, где можно обнаружить журнал изменений:
- В посте блога. Changelog может вестись в отдельной статье, где описываются последние изменения в проекте.
- Файл CHANGELOG.md — в репозитории на GitHub.
- Раздел Changelog на сайте вашего любимого ПО. Например, вот changelog инструмента для менеджмента задач TickTick.
- Раздел «Что нового» («What’s new») на страницах приложений в Android и IOS store.
Автоматическое генерирование changelog-а
Сейчас мы создадим наш первый changelog. Занимаясь этой задачей, вы увидите, в чем польза соблюдения определенных правил при написании сообщений коммитов.
Хорошее, исчерпывающее сообщение коммита вообще не нужно менять — его можно вносить в changelog, как есть.
Если вы хотите сгенерировать файл changelog-а, никак его не украшая и не персонализируя, я рекомендую воспользоваться самым простым способом и создать этот файл из сообщений коммитов.
Примечание. Некоторые сайты, например, Keep A Changelog, поясняют, что не следует создавать changelog путем копипаста сообщений git-коммитов (простой способ). Я тоже не советую обращаться к этому способу, если вы создаете профессиональный продукт. Но сегодня есть еще и специальные продвинутые генераторы, которые позволяют превращать ваши git log-и в changelog-и (более сложный способ).
Простой способ генерирования changelog-а
Чтобы сгенерировать changelog простым способом, вам не нужно никаких дополнительных инструментов или предварительных действий. Вам понадобится лишь ввести несколько команд, находясь в вашем Git-репозитории.
Начнем с напоминания. Когда вы вводите команду git log, выводится весь список ваших коммитов.
$ git log // Output commit f6986f8e52c1f889c8649ec75c5abac003102999 (HEAD -> master, origin/master, origin/HEAD) Author: Sam Katakouzinos sam.katakouzinos@gmail.com Date: Tue Mar 10 11:41:18 2020 +1100docs(developers): commit message format typo Any line of the commit message cannot be longer *than* 100 characters! Closes #17006commit ff963de73ab8913bce27a1e75ac01f53e8ece1d9 Author: Chives chivesrs@gmail.com Date: Thu Feb 6 19:05:57 2020 -0500docs($aria): get the docs working for the service Closes #16945commit 2b28c540ad7ebf4a9c3a6f108a9cb5b673d3712d Author: comet hjung524@gmail.com Date: Mon Jan 27 19:49:55 2020 -0600docs(*): fix spelling errors Closes #16942
Эта команда может принимать несколько параметров. Мы ими воспользуемся, чтобы видоизменить вывод команды и улучшить его.
Введя git log —oneline —decorate, мы получим список коммитов, каждый из которых будет занимать одну строчку.
$ git log --oneline --decorate // Output f6986f8e5 (HEAD -> master, origin/master, origin/HEAD) docs(developers): commit message format typo ff963de73 docs($aria): get the docs working for the service 2b28c540a docs(): fix spelling errors 68701efb9 chore(): fix serving of URI-encoded files on code.angularjs.org c8a6e8450 chore(package): fix scripts for latest Node 10.x on Windows 0cd592f49 docs(angular.errorHandlingConfig): fix typo (wether --> whether) a4daf1f76 docs(angular.copy): fixgetter/setterformatting be6a6d80e chore(*): update copyright year to 2020 36f17c926 docs: add mention to changelog ff5f782b2 docs: add mention to changelog 27460db1d docs: release notes for 1.7.9 add78e620 fix(angular.merge): do not merge proto property
Вид уже получше, но можно и усовершенствовать.
$ git log --pretty=”%s” // Output docs(developers): commit message format typo docs($aria): get the docs working for the service docs(): fix spelling errors chore(): fix serving of URI-encoded files on code.angularjs.org chore(package): fix scripts for latest Node 10.x on Windows docs(angular.errorHandlingConfig): fix typo (wether --> whether) docs(angular.copy): fixgetter/setterformatting chore(*): update copyright year to 2020 docs: add mention to changelog docs: add mention to changelog docs: release notes for 1.7.9 fix(angular.merge): do not merge proto property
Здесь мы выводим список коммитов в желанном для нас стиле. «%s» относится к названию коммита. Все остальные части вывода можно модифицировать, чтобы результат выглядел так, как вам нужно. Например, можно добавить дефис перед каждым коммитом:
$ git log --pretty="- %s" // Output - docs(developers): commit message format typo - docs($aria): get the docs working for the service - docs(*): fix spelling errors - chore(*): fix serving of URI-encoded files on code.angularjs.org - chore(package): fix scripts for latest Node 10.x on Windows - docs(angular.errorHandlingConfig): fix typo (wether --> whether) - docs(angular.copy): fixgetter/setterformatting - chore(*): update copyright year to 2020 - docs: add mention to changelog - docs: add mention to changelog - docs: release notes for 1.7.9 - fix(angular.merge): do not merge proto property
Вот и все! Вы создали простой changelog.
Примечание. Если вы хотите сохранить полученный changelog, не нужно его копипастить. Просто перенаправьте вывод команды в файл с нужным названием. Например,
git log --pretty="- %s" > CHANGELOG.md
Более сложный способ генерирования changelog-а
Здесь сама идея — генерирование changelog-а на основе сообщений коммитов — сохраняется, но мы будем пользоваться специальными инструментами.
При написании сообщений коммитов рекомендуется придерживаться определенного стиля. Эти стили зависят от набора правил, которым вы пользуетесь, а правила изложены в специальных руководствах. Например, есть простое руководство от Udacity. Есть и другие: Conventional Commits, Angular Guideline. Следуя прописанным в руководствах правилам, вы делаете свои сообщения более структурированными.
Хорошо структурированные коммиты позволяют вам воспользоваться специальными инструментами для генерирования changelog-а. Чаще всего таким образом можно получить лучший результат, потому что эти инструменты позволяют создавать форматированные (markdown) changelog-и.
В нашем примере мы воспользуемся простым генератором, который работает с большинством руководств по стилю коммитов. Он называется «generate-changelog» и доступен на NPM (Node Package Manager).
Этот инструмент, хотя у него и небогатый функционал, создаст более стильный changelog, чем просто текстовый файл, сгенерированный из командной строки. Если хотите пойти дальше, обратите внимание на другие инструменты генерации changelog-ов:
Установка и использование generate-changelog
Прежде чем устанавливать этот инструмент, нужно убедиться, что у вас установлен NPM. Если нет, установите Node и NPM, следуя указаниям на официальном сайте.
Для установки пакета на свой компьютер, введите в терминале следующую команду:
$ npm install generate-changelog -g
Использование
Чтобы этот инструмент работал, вы должны при написании сообщений коммитов пользоваться шаблоном «тип(категория): описание [флаги]». В этом примере я буду использовать GitHub-репозиторий Angular.js, потому что там разработчики придерживаются именно такого шаблона.
Установив пакет, вы можете перейти в свой GitHub-репозиторий и выполнить следующую команду:
$ changelog generate
Файл CHANGELOG.md будет создан автоматически. Он будет содержать ваши логи в формате markdown.
Ниже представлен пример вывода команды (в том виде, в каком он будет доступен к просмотру на GitHub или при помощи markdown-ридера).
Заключение
Теперь вы знаете, как создать changelog для своего проекта. Также, надеюсь, теперь вы лучше понимаете, почему так важно писать хорошие сообщения коммитов.
