IT-инфраструктура для бизнеса и творчества
Разработка
Daniil Lebedev

Руководство для начинающих по 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).

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

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

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

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

$ npm install generate-changelog -g

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

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

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

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

$ changelog generate

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

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

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

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

Автор: Gaël Thomas.

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

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

(function () { let cdnUrl = `https://specialsf378ef5-a.akamaihd.net/SelectelBranding/images/` let previousArticleNumber = null let currentArticleNumber = 0 let platform = 'Desktop' let articles = [ { name: 'camera', url: `${cdnUrl}CameraCat`, text: 'умную камеру для\u00A0наблюдения за\u00A0котиками', link: 'https://vc.ru/selectel/306690', num: 3 }, { name: 'chill', url: `${cdnUrl}ChillCat`, text: 'трекер, который подскажет, когда пора отдохнуть', link: 'https://vc.ru/promo/288561-eye-tracker', num: 1 }, { name: 'cloud', url: `${cdnUrl}CloudCat`, text: 'котика: даёшь ему «пять», а\u00A0он делает бэкап в облако', link: 'https://vc.ru/dev/294799-maneki-neko', num: 2 } ] let buttonCycle = document.querySelector('.button--cycle') let buttonChoose = document.querySelector('.button--choose') let buttonMobile = document.querySelector('.button--mobile') let textField = document.querySelector('.selectel-footer-subtitle') let imageAgent = document.querySelector('.image--agent') let banner = document.querySelector('.selectel-footer') buttonCycle.addEventListener('click', cycleClick) buttonChoose.addEventListener('click', () => sendEvent(`Promo ${articles[currentArticleNumber].num} Left`, 'Click')) buttonMobile.addEventListener('click', () => sendEvent(`Promo ${articles[currentArticleNumber].num} Left`, 'Click')) let media = window.matchMedia("(max-width: 570px)") media.addEventListener('change', matchMedia) function matchMedia() { if (media.matches) { platform = 'Mobile' } else { platform = 'Desktop' } update() } matchMedia() function cycleClick(event) { sendEvent(`Promo ${articles[currentArticleNumber].num} Right`, 'Click') if (event) { event.preventDefault() event.stopPropagation() } window.open('https://vc.ru/tag/selectelDIY', '_blank') //cycle(event) } function cycle(event) { // incrementArticleNumber() textField.innerHTML = generatedText() imageAgent.src = articles[currentArticleNumber].url + platform + '.svg?3' imageAgent.setAttribute("class", "") imageAgent.classList.add('image--agent', articles[currentArticleNumber].name) banner.href = articles[currentArticleNumber].link } function update() { banner.href = articles[currentArticleNumber].link imageAgent.src = articles[currentArticleNumber].url + platform + '.svg' textField.innerHTML = generatedText() } function incrementArticleNumber() { previousArticleNumber = currentArticleNumber if (currentArticleNumber >= articles.length - 1) { currentArticleNumber = 0 } else { currentArticleNumber++ } } const sendEvent = (label, action = 'Click') => { const value = `SelectelDIY — loc: Footer — ${label} — ${action}`; if (window.dataLayer !== undefined) { window.dataLayer.push({ event: 'data_event', data_description: value, }); } }; function generatedText() { let defaultText if (platform === 'Desktop') { defaultText = `Мы тут собрали %text%. Хотите научим?` } else { defaultText = `Мы тут собрали %text%.` } return defaultText.replace('%text%', articles[currentArticleNumber].text) } function getRandom(min, max) { min = Math.ceil(min) max = Math.floor(max) return Math.floor(Math.random() * (max - min + 1)) + min } (function create() { currentArticleNumber = getRandom(0, articles.length - 1) cycle() let page = document.querySelector('.page--entry') if (page) { function insertAfter() { let parents = page.querySelectorAll('[data-id="7"]') let referenceNode = parents[0] referenceNode.parentNode.insertBefore(banner, referenceNode.nextSibling); loaded() } setTimeout(() => insertAfter(), 0) } }()) function loaded() { banner.classList.add('loaded') } loadImages([ `${cdnUrl}CameraCatDesktop.svg`, `${cdnUrl}ChillCatDesktop.svg`, `${cdnUrl}CloudCatDesktop.svg`, `${cdnUrl}CameraCatMobile.svg`, `${cdnUrl}ChillCatMobile.svg`, `${cdnUrl}CloudCatMobile.svg?3`, ]) function loadImages(urls) { return Promise.all(urls.map(function (url) { return new Promise(function (resolve) { var img = document.createElement('img'); img.onload = resolve; img.onerror = resolve; img.src = url; }); })); } }())
0
4 комментария
Популярные
По порядку
Читать все 4 комментария
Невидимый убийца: как воздух в вашем офисе делает вас глупее

Важное исследование, которое должно заставить все компании пересмотреть свои офисы.

Бизнесменам разрешат перевести личные фонды в российские офшоры

Согласно проекту поправок Минэкономразвития РФ к закону "О международных компаниях и международных фондах" министерство планирует разрешить бизнесменам регистрировать в так называемых русских офшорах - специальных административных районах (САР) в Калининграде и Владивостоке - личные фонды и трасты.

Мысли создателя FastAPI Себастьяна Рамиреса из интервью Evrone

Себастьян Рамирез — энтузиаст open source, создатель таких популярных инструментов, как FastAPI, Typer и SQLModel. В интервью он поделился мнением о собственных проектах, образовании для разработчиков и собственной популярности в Twitter. Полный текст доступен по ссылке.

Минэнерго включило в правила для субсидий на зарядные станции медленную зарядку и четыре выхода для электромобилей Статьи редакции

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

Что такое digital nomad виза и как ее получить?

Одним из плюсов жизни цифрового кочевника (digital nomad) является возможность попасть в страны, закрытые для всех туристов во время пандемии. Ещё digital nomad виза, которую иногда также называют визой удаленного работника, дает право проживать и работать в определенной стране на протяжении большого периода времени. В статье мы расскажем о ее…

Опыт возврата денег за обучение дизайну у Yakovlevv.com. Тварь я дрожащая или право имею?
Новые гарантии для одиноких родителей

Государственная Дума РФ 9 ноября 2021 года приняла в третьем чтении закон, предоставляющий дополнительные гарантии отдельным категориям работников, имеющих несовершеннолетних дней, и вносящий поправки в Трудовой Кодекс РФ.

Омикрон проверит работоспособность стратегии покупки акций на спадах

Появление варианта омикрон позволит вновь проверить работоспособность стратегии покупки на спадах, которая в этом году пока сбоев не давала.

Сервис «Кухня на районе» отменил бесплатную доставку еды Статьи редакции

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

Что там с видеорегистраторами: где за них штрафуют, а где — дают скидку на страховку

Регуляторы вновь в деле. На этот раз они могут затронуть видеорегистраторы. Расскажу о ситуации с точки зрения страхового эксперта.

MIKI Yoshihito / Flickr / CC BY 2.0
null