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

Допустим, вы разработчик и на одном из ваших проектов используете Git. Вы хотите поделиться сделанными вами изменениями с другими пользователями, но не знаете, как. Тогда эта статья специально для вас.

В этой статье вы узнаете, что такое журнал изменений (changelog), а также два способа его создания: простой и сложный.

Что такое журнал изменений?

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

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

• Обычный способ: создайте текстовый файл и начните перечислять все внесенные вами изменения с указанием определенной даты.
• Выбор разработчика (он же вариант для ленивых): автоматическое создание списка изменений из ваших сообщений к коммитам. У меня для вас хорошие новости — именно об этом вы узнаете из этой статьи!

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

Почему он так важен?

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

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

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

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

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

Где их искать?

Журналы изменений повсюду! Зачастую они различаются по стилю и месту расположения, но есть буквально в каждом проекте.

Я создал короткий список нескольких мест, где вы можете найти журналы изменений:

• Пост в блоге. Список изменений может быть представлен в виде статьи, излагающей содержание самых недавних фич.
• Файл CHANGELOG.md в репозитории GitHub.
• Раздел “Журнал изменений” (“Changelog”) вашего любимого сайта/ПО. Вот пример инструмента управления задачами TickTick.
• Раздел “Что нового?” в Android Google Play и iOS AppStore.

Автоматическая генерация журнала изменений

В этой части мы вместе создадим наш первый журнал изменений.

Выполнив эту задачу, вы поймете, почему полезно делать коммиты, следуя определенным правилам. 

Отличный и очевидный коммит не нуждается в модификациях и может быть добавлен в журнал изменений напрямую.

Если вы заинтересованы в создании необходимого файла без какой-либо персонализации или преобразований, я рекомендую первый способ; в противном случае лучше использовать второй.

Примечание: Некоторые веб-сайты, такие как Keep A Changelog, поясняют, что вы не должны создавать список изменений исключительно путем копирования и вставки ваших git-коммитов (см. простой способ). Я и в самом деле рекомендую избегать подобного способа, если вы работаете над профессиональным продуктом.

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

Как создать журнал изменений (простой способ)

При использовании этого способа вам не потребуется никакой предварительной подготовки. Все, что вам нужно, — это ввести несколько команд в своем Git-репозитории.

В качестве простого напоминания: когда вы набираете команду “git log”, отображается список всех ваших коммитов.

$ git log



// Вывод

commit f6986f8e52c1f889c8649ec75c5abac003102999 (HEAD -> master, origin/master, origin/HEAD)

Author: Sam Katakouzinos <[email protected]>

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 <[email protected]>

Date:   Thu Feb 6 19:05:57 2020 -0500



    docs($aria): get the docs working for the service

    

    Closes #16945



commit 2b28c540ad7ebf4a9c3a6f108a9cb5b673d3712d

Author: comet <[email protected]>

Date:   Mon Jan 27 19:49:55 2020 -0600



    docs(*): fix spelling errors

    

    Closes #16942

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

Набрав следующую команду, вы получите вывод, в котором каждый коммит будет находиться на отдельной строке:

$ git log --oneline --decorate



// Вывод

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"



// Вывод

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"



// Вывод

- 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

Мы сделали это! Мы создали простейший журнал изменений!

Примечание: если вы хотите продвинуться дальше и сохранять свой список изменений быстрее, то вместо копирования и вставки результата в файл, перенаправьте его в терминал, набрав git log — pretty=” — %s “ > CHANGELOG.md.

Как создать журнал изменений (сложный способ)

Предварительная подготовка

Теперь мы рассмотрим сложный способ создания журнала изменений. Идея, лежащая в основе, остается прежней, но на этот раз мы используем другие инструменты. 

Примечание: гайдлайны Git — это наборы правил для лучшего написания коммитов, которые помогают их структурировать. 

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

В этом примере мы будем использовать простой генератор, который работает с большинством гайдлайнов. Он называется “generate-changelog” и доступен через NPM (Node Package Manager). 

Этот инструмент создает стилизованный список изменений, однако не обладает большим функционалом. Я решил использовать его, потому что это отличный пример для новичка. Если вам хочется продвинуться дальше, обратите внимание на список инструментов ниже.

Вот те инструменты, которыми вы можете воспользоваться:

• Github Changelog Generator;
• Git Chglog;
• Auto Changelog;
• Conventional Changelog.

Примечание: Прежде чем устанавливать инструмент, убедитесь, что на вашем компьютере уже установлен NPM. Если нет, то я приглашаю вас на официальный сайт (он поможет вам установить Node и NPM).

Чтобы установить пакет себе на компьютер, введите в терминале следующую команду:

$ npm install generate-changelog -g

Установка закончена!

Как использовать инструмент

Чтобы заставить этот пакет работать, вам нужно следовать гайдлайнам по использованию такого шаблона: “тип (категория): описание [флаги]”. В этом примере я буду использовать репозиторий Angular.js на GitHub.

Теперь вы можете ввести команду generate в своем терминале внутри репозитория GitHub:

$ changelog generate

Файл “CHANGELOG.md” будет создан автоматически и заполнен вашими журнальными записями в markdown-формате.

Ниже вы можете найти пример вывода (с помощью программы чтения, поддерживающей markdown, такой как GitHub):

Заключение

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

Не стесняйтесь пробовать другие генераторы журнала изменений и делиться результатами!