Посібник для початківців по Git - що таке журнал змін і як його створити

Скажімо, ви розробник і використовуєте Git для одного зі своїх проектів. Ви хочете поділитися своїми змінами зі своїми користувачами, але не знаєте як. Ну, тоді ця стаття для вас.

В останній частині цієї серії я поділився з вами, як написати хороше повідомлення про коміт.

Я дав вам огляд переваг написання хорошого коміту і згадав про можливість створення журналу змін.

У цій статті ви дізнаєтеся, що таке журнал змін, а також два способи його створення - простий і складний.

Що таке журнал змін?

Журнал змін - це файл, який надає хронологічно упорядкований список змін, внесених у ваш проект. Це часто організовується за версією з датою, за якою додається список доданих, вдосконалених та видалених функцій.

У всьому світі є два способи написати журнал змін:

  • звичайний спосіб: створіть текстовий файл і починайте перераховувати всі зміни до певної дати
  • вибір розробника (псевдонім ледачий варіант): автоматично генерувати ваш журнал змін із ваших повідомлень про коміти. У мене є для вас хороші новини - це те, про що ви збираєтесь дізнатися в цій статті!
“Журнал змін - це журнал або запис усіх помітних змін, внесених до проекту. Проект часто є веб-сайтом або програмним проектом, і журнал змін зазвичай включає записи змін, такі як виправлення помилок, нові функції тощо ". - Вікіпедія

Чому це важливо?

Думаю, навіть зараз ви запитуєте себе, чому це важливо і чому вам слід витратити час на його створення.

Журнал змін - це свого роду підсумок усіх ваших змін. Це має бути легко зрозуміти як користувачам, що використовують ваш проект, так і розробникам, які працюють над ним.

У світі, де все швидко розвивається, користувач повинен знати, чи змінюється веб-сайт / програмне забезпечення, яким вони користуються. Ви можете бути здивовані, але люди люблять читати публікації в блозі або сторінки оновлення на вашому веб-сайті.

Наприклад, для розробника, якщо проект великий, може бути цікаво знати, як розвивається програмне забезпечення, над яким вони працюють.

Або якщо ви працюєте над проектом з відкритим кодом, ви можете знайти файл "CHANGELOG.md" у сховищі GitHub. Цей файл має на меті інформувати учасників про останні оновлення проекту.

Де ми їх знаходимо?

Журнали змін є скрізь! Гаразд, вони часто мають різні стилі та місця розташування, але вони буквально стосуються кожного проекту.

Я створив короткий список із кількома місцями, де ви можете знайти журнал змін.

  • Повідомлення в блозі. Журнал змін може бути представлений за статтею, де пункти за пунктом викладаються останні функції.
  • Файл "CHANGELOG.md" у сховищі GitHub.
  • Розділ журналу змін на вашому улюбленому веб-сайті / програмному забезпеченні. Ось один приклад із інструментом управління завданнями TickTick.
  • В "Що нового" на Android та магазині IOS.

Автоматичне створення журналу змін

У цій частині ми збираємось створити наш перший журнал змін разом.

Виконуючи це завдання, ви зрозумієте, чому це може бути корисно здійснити, дотримуючись деяких правил.

Відмінний і явний коміт не потребує модифікації і може бути доданий безпосередньо до журналу змін.

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

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

Однак сьогодні є кілька вдосконалених генераторів, які дозволяють вам змінити свої журнали git на журнали змін (зверніться до вишуканого способу).

Як створити журнал змін (простий спосіб)

Використовуючи цей перший спосіб, вам не потрібні жодні передумови. Все, що вам потрібно, це набрати кілька команд у вашому сховищі Git.

Для простого нагадування, коли ви вводите "git log", відображається список усіх ваших комітів.

$ git log // Output commit f6986f8e52c1f889c8649ec75c5abac003102999 (HEAD -> master, origin/master, origin/HEAD) Author: Sam Katakouzinos  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  Date: Thu Feb 6 19:05:57 2020 -0500 docs($aria): get the docs working for the service Closes #16945 commit 2b28c540ad7ebf4a9c3a6f108a9cb5b673d3712d Author: comet  Date: Mon Jan 27 19:49:55 2020 -0600 docs(*): fix spelling errors Closes #16942

Ця команда може приймати кілька параметрів. Ми збираємося використовувати їх, щоб змінити результат і отримати вдосконалений для створення нашого журналу змін.

Набравши наступну команду, ви отримаєте результат з одним комітом на рядок.

$ git log --oneline --decorate // Output 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” // Output 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" // Output - 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?

Примітка : Правила Git - це набір правил для кращого написання ваших комітів. Ці вказівки допоможуть вам додати певну структуру до своїх комітів.

Коли ви використовуєте керівництво для свого проекту, ви можете використовувати інструменти для створення журналу змін. Здебільшого ці інструменти є кращими, оскільки дозволяють створювати відформатований журнал змін.

У цьому прикладі ми будемо використовувати простий генератор, який працює з більшістю рекомендацій. Її назва - “create-changelog”, і вона доступна на NPM (менеджер пакетів вузлів).

Цей інструмент збирається створити стилізований журнал змін, але це не той, що має найбільшу кількість функцій. Я вирішив ним скористатися, оскільки це чудовий приклад для початківців. Якщо ви хочете піти далі, зверніться до списку інструментів журналу змін нижче:

Ось декілька інструментів, якими ви можете скористатися:

  • Генератор журналів змін Github
  • Git Chglog
  • Автоматичний журнал змін
  • Звичайний журнал змін
Примітка. Перш ніж встановлювати інструмент, потрібно встановити NPM на комп’ютері. Якщо у вас його немає, я запрошую вас перейти на офіційний веб-сайт (це допоможе вам встановити Node та NPM).

Щоб встановити пакет на свій комп’ютер, введіть таку команду у своєму терміналі.

$ npm install generate-changelog -g 

Як тільки ви це зробите, це буде встановлено!

Як ним користуватися

Щоб цей пакет працював, вам потрібно дотримуватися вказівок щодо використання цього шаблону - “тип (категорія): опис [прапори]”. У цьому прикладі я буду використовувати сховище Angular.js GitHub.

Тепер ви можете ввести команду create у своєму терміналі всередині вашого сховища GitHub.

$ changelog generate

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

Нижче ви можете знайти приклад результату (із зчитувачем націнки, таким як GitHub).

Висновок

Сподіваюся, вам сподобався цей посібник і тепер ви розумієте, як створити журнал змін для вашого проекту. Я думаю, що це хороший спосіб продемонструвати, чому ви повинні писати хороші повідомлення про коміти.

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

Якщо у вас є запитання чи відгуки, будь ласка, повідомте мене.

Не пропустіть мій вміст, слідкуючи за мною у Twitter та Instagram.

You can find other articles like this on my website: herewecode.io.

Want more?

  • Each week get a motivational quote with some advice, a short tutorial in a few slides, and one developer's picture on Instagram.
  • Sign-up for the newsletter and get the latest articles, courses, tutorials, tips, books, motivation, and other exclusive content.