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 комментария
Минэнерго включило в правила для субсидий на зарядные станции медленную зарядку и четыре выхода для электромобилей Статьи редакции

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

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

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

Новые гарантии для одиноких родителей

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

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

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

MIKI Yoshihito / Flickr / CC BY 2.0
Что такое digital nomad виза и как ее получить?

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

Невидимый убийца: как воздух в вашем офисе делает вас глупее

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

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

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

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

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

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

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

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