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

0
754
views

Перевод статьи «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 для своего проекта. Также, надеюсь, теперь вы лучше понимаете, почему так важно писать хорошие сообщения коммитов.

ОСТАВЬТЕ ОТВЕТ

Please enter your comment!
Please enter your name here