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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

С ее помощью вы можете вывести список коммитов в нужном вам стиле.

«%s» здесь соответствует непосредственно заголовку коммита. Вы можете изменить строку, чтобы стиль отображения коммитов был таким, как вам нравится.

В нашем случае мы хотим создать список:

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

Примечание: если вы хотите продвинуться дальше и сохранять свой список изменений быстрее, то вместо копирования и вставки результата в файл, перенаправьте его в терминал, набрав: 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):

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

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

Автор: Gaël Thomas.

Перевод: Лебедев Даниил.

Еще больше полезной и нужной информации вы найдете в нашем Телеграм-канале.

#git