Что такое changelog проекта и как его создать: руководство по Git для начинающих

Перевод статьи «A Beginner’s Guide to Git — What is a Changelog and How to Generate it».

Photo by Mark Rasmuson on Unsplash

Итак, вы — разработчик и хотите использовать Git для одного из своих проектов. При этом вы хотите сообщать пользователям вашего приложения об осуществленных вами изменениях, но не знаете, как это сделать. Данная статья поможет вам в этом.

Мы рассмотрим, что такое changelog, а также познакомимся с двумя способами его создания — простым и более сложным.

Что такое changelog?

Changelog это файл, в котором содержится хронологически упорядоченный список изменений, внесенных в проект. Он часто создается на основе версий ПО — с указанием дат их выхода и списками добавленных, исправленных и удаленных функций.

«Журнализация изменений проекта (англ. changelog) представляет собой программное протоколирование изменений, вносимых в большой проект. Обычно записи журнала изменений содержат информацию об исправлении ошибок, о новых возможностях и т.д.», — Википедия.

В целом, есть два способа вести changelog:

  1. простой — создать текстовый файл и начать перечислять в нем все вносимые изменения с указанием дат;
  2. «программистский» (или ленивый) — автоматически генерировать changelog из сообщений коммитов.

Мы остановимся на втором способе.

Зачем нужен changelog?

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

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

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

Разработчикам, работающим над крупным проектом, может быть интересно, как этот проект развивается.

Если вы работаете над проектом с открытым кодом, вы можете найти файл CHANGELOG.md в GitHub-репозитории. Этот файл информирует контрибьюторов о последних обновлениях проекта.

Пример changelog проекта с открытым кодом

Где можно найти changelog-и?

Changelog-и встречаются повсюду! Они могут принимать разные формы и располагаться в разных местах, но они есть буквально в каждом проекте.

Вот краткий список мест, где можно обнаружить журнал изменений:

  • В посте блога. Changelog может вестись в отдельной статье, где описываются последние изменения в проекте.
  • Файл CHANGELOG.md — в репозитории на GitHub.
  • Раздел Changelog на сайте вашего любимого ПО. Например, вот changelog инструмента для менеджмента задач TickTick.
  • Раздел «Что нового» («What’s new») на страницах приложений в Android и IOS store.
Раздел «Что нового» приложения TickTick на Android
Раздел «Что нового» приложения TickTick на IOS

Автоматическое генерирование 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 +1100
docs(developers): commit message format typo Any line of the commit message cannot be longer *than* 100 characters! Closes #17006
commit ff963de73ab8913bce27a1e75ac01f53e8ece1d9
Author: Chives chivesrs@gmail.com
Date:   Thu Feb 6 19:05:57 2020 -0500
docs($aria): get the docs working for the service Closes #16945
commit 2b28c540ad7ebf4a9c3a6f108a9cb5b673d3712d
Author: comet hjung524@gmail.com
Date:   Mon Jan 27 19:49:55 2020 -0600
docs(*): 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): fix getter/setter formatting
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): fix getter/setter formatting
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): fix getter/setter formatting
- 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 для своего проекта. Также, надеюсь, теперь вы лучше понимаете, почему так важно писать хорошие сообщения коммитов.

[customscript]techrocks_custom_after_post_html[/customscript]

[customscript]techrocks_custom_script[/customscript]

Оставьте комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

Прокрутить вверх