Допустим, вы разработчик и на одном из ваших проектов используете 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).
Этот инструмент создает стилизованный список изменений, однако не обладает большим функционалом. Я решил использовать его, потому что это отличный пример для новичка. Если вам хочется продвинуться дальше, обратите внимание на список инструментов ниже.
Вот те инструменты, которыми вы можете воспользоваться:
Примечание: Прежде чем устанавливать инструмент, убедитесь, что на вашем компьютере уже установлен NPM. Если нет, то я приглашаю вас на официальный сайт (он поможет вам установить Node и NPM).
Чтобы установить пакет себе на компьютер, введите в терминале следующую команду:
$ npm install generate-changelog -g
Установка закончена!
Как использовать инструмент
Чтобы заставить этот пакет работать, вам нужно следовать гайдлайнам по использованию такого шаблона: “тип (категория): описание [флаги]”. В этом примере я буду использовать репозиторий Angular.js на GitHub.
Теперь вы можете ввести команду generate в своем терминале внутри репозитория GitHub:
$ changelog generate
Файл “CHANGELOG.md” будет создан автоматически и заполнен вашими журнальными записями в markdown-формате.
Ниже вы можете найти пример вывода (с помощью программы чтения, поддерживающей markdown, такой как GitHub):
Заключение
Я надеюсь, что вам понравилось это руководство и теперь вы понимаете, как создавать журнал изменений для своего проекта. Думаю, это хороший способ продемонстрировать, почему следует писать хорошие комментарии к коммитам.
Не стесняйтесь пробовать другие генераторы журнала изменений и делиться результатами!
Читайте также:
- Команда Git Rerere — автоматизируйте решения для устранения конфликтов слияния
- Отмена действий в Git
- Индексирование коммитов с Git Add Patch
Перевод статьи Gaël Thomas: “A Beginner’s Guide to Git — What is a Changelog and How to Generate it”