Захистіть ваші сайти з My-Sites-Guard.com! Коли розробник пише код, йому здається, що зміни очевидні. Проте за кілька днів, а тим більше місяців, розуміння суті внесених змін може стати складним завданням. У команді програмістів це ще більше посилюється: навіть якщо код зрозумілий самому автору, колегам може бути складно розібратися в ньому без чітких коментарів. Повідомлення коммітів допомагають у цьому — вони є своєрідною документацією до коду. Крім того, багато інструментів контролю версій, таких як Git, дозволяють швидко та ефективно відслідковувати історію змін, повертатися до певних коммітів та розбиратися в тому, чому було прийнято те чи інше рішення. Приклад: при виникненні помилки ви завжди зможете швидко знайти коміт, який викликав проблему, якщо коментарі до комітів складено правильно. Добре написане повідомлення до комміту допомагає іншим членам команди швидко зрозуміти його суть, допомагає уникнути необхідності вивчати кожен рядок коду для розуміння змін. З іншого боку, погано написане або неінформативне повідомлення ускладнює аналіз змін, і зрештою витрачає час усієї команди. Щоб коміт був зрозумілим та корисним іншим, повідомлення до нього має бути ясним, інформативним і відповідати деяким основним правилам. 1. Починайте повідомлення з дієслова у наказовому способі. Наказовий спосіб робить повідомлення більш конкретними і націленими на дію, що полегшує розуміння суті змін. Приклад: "Додати функцію обробки помилок" замість "Додано функцію обробки помилок". Наказові дієслова ясно дають зрозуміти, що було зроблено і навіщо. 2. Використовуйте короткі повідомлення. Намагайтеся не перевантажувати повідомлення надмірною інформацією, але й не спрощуйте їх до одного рядка. Знайдіть баланс: важливі деталі слід вказувати, а другорядні - упускати. Приклад: "Виправити баг із завантаженням зображень на головній сторінці" або "Оптимізувати SQL-запит у модулі авторизації". 3. Спочатку вкажіть, що було зроблено, а потім чому. Щоб підвищити читабельність, перша пропозиція має відповідати на запитання "Що?", а наступна - на "Чому?" або "Як?" Приклад: "Видалити застарілий модуль логування. Це зменшить час завантаження на 10%." 4. Уникайте термінів, незрозумілих для всієї команди. Повідомлення повинні бути написані так, щоб будь-який член команди міг їх зрозуміти, навіть якщо він не брав участі у розробці даного фрагмента коду. Якщо вам потрібно використовувати технічний термін, переконайтеся, що він є загальновідомим або поясніть його в коментарі. 5. Не бійтеся пояснити складні зміни. Коли зміни великі або торкаються кількох компонентів, додайте більше деталей у повідомлення. Приклад: "Рефакторинг функції обробки замовлень. Тепер код розбитий на окремі компоненти для покращення читаності та тестування." Помилки в коментарях до коммітів можуть ускладнити відстеження історії змін та їх аналіз, тому намагайтеся уникати їх. Розглянемо найпоширеніші помилки та способи їх запобігти. 1. Надто короткі або абстрактні повідомлення. Повідомлення на кшталт "Виправлено", "Оновлено", "Допрацьовано" або просто "Багфікс" не дають жодної конкретної інформації. Таке повідомлення не допоможе зрозуміти, який саме баг було виправлено або що було оновлено. Краще: "Виправити помилку з анімацією на мобільних пристроях." 2. Надлишкові коментарі чи особисті нотатки. Повідомлення коммітів не повинні містити зайву особисту інформацію чи жарти. Уникайте довгих пояснень, які не стосуються коду. Повідомлення на кшталт "Нарешті впорався!" або "Жахливий баг" не додають користі і навіть можуть викликати плутанину. 3. Використання непотрібних скорочень. Якщо скорочення використовуються часто, це може заплутати, особливо якщо вони не є загальноприйнятими у вашій компанії. Наприклад, повідомлення типу "Fixed BG on MFP" (виправлений баг у модулі функцій користувача) можуть стати неясними для інших. Краще: "Виправити баг із відображенням на сторінці функцій." 4. Довгі повідомлення без структури. Якщо повідомлення до комміту вийшло довгим, зробіть його більш структурованим, додавши, у разі потреби, підзаголовки або ключові моменти, розділені точками. Це допоможе колегі чи вам самим швидше зрозуміти зміст повідомлення. Часто певні типи коммітів потребують особливого підходу до повідомлень. Розглянемо кілька популярних сценаріїв та приклади повідомлень до них. Додавання нової функції
Виправлення помилки
Рефакторинг коду
Оновлення документації
Оновлення залежностей
Save DmitriiNazimov/f9cf7d0631d12c19827518b8bd8134c4 для вашого комп'ютера і використовувати його в GitHub Desktop. Як основа використовується Angular Git commit Message Convention - це найбільш авторитетне джерело. Всі інші варіації конвенцій щодо комітів посилаються на цю. Також досить авторитетним джерелом є conventionalcommits.org Нижче наведено коротке вичавлення того, як я зрозумів ці конвенції. Для оформлення повідомлення комміту слід використовувати наступний шаблон: Type, scope та description разом становлять заголовок комміта (header). У результаті виходить приблизно так: Щоб було простіше писати коміти за всіма правилами для VS Code, є плагін "Commit Message Editor". Якщо використовувати його для написання тексту коммітів, то помилитись неможливо. У плагіна дві вкладки - edit as text та edit as form. Безпомилковий варіант – це edit as form. Найчастіше використовуваний тип - refactor. Ці типи розширюють вищеописані, але їх використовувати не обов'язково: BREAKING CHANGE: вказується у футері і автоматично додається до кінця заголовка. Критичні зміни – це зміни, що порушують зворотну сумісність. Може бути частиною коміту будь-якого типу. Повинний починатися з фрази BREAKING CHANGE: , за якою слідує короткий виклад критичної зміни, порожній рядок та докладний опис критичної зміни. Перед тим як пушити комміти на сервер, варто їх перевірити: Якщо якісь проблеми є, їх бажано виправити. Незрозумілим чи не зовсім коректним комітам варто оновити текст повідомлення, а зайві коміти можна поєднати з іншими коммітами. Як виправити проблеми? Використовувати команду git rebase -i. З її допомогою можна розставити коммиты у правильному порядку, об'єднати їх, перейменувати, тощо. Але з цією командою треба бути обережним та діяти акуратно. Не можна використовувати rebase у публічних (вже запушених) гілках! Лише у локальних гілках розробки, які ще були запушены. Відео-інструкція як працювати з командою git rebase-i. Заглянувши в історію змін (коммітів) якогось рандомного Git-репозиторію, ви напевно помітите, що описи коммітів (commit messages) написані тією чи іншою мірою безладно. Наприклад, подивіться на описи коммітів, які я написав, коли починав контриб'ютити у Spring: Виглядає не дуже привабливо. Тепер подивіться на описи пізніших коммітів у тому самому репозиторії. Які з цих описів ви читаєте охочіше? Старі відрізняються формою і за довжиною, а нові більш лаконічні та одноманітні. Старі начебто написані хаотично і без системи, а нові явно писалися усвідомлено і за впорядкованими правилами. Як уже говорив, приклади безладних описів можна знайти історія змін різних репозиторіїв. Але є приємні винятки, наприклад, репозиторії ядра Linux та самого Git. Контриб'ютори цих репозиторіїв розуміють, що правильно оформлені описи — найкращий спосіб передати контекст комміту іншим контриб'юторам, а також майбутньому собі. Діф допомагає зрозуміти, що саме змінює коміт. Але тільки описи коммітів допоможуть зрозуміти, навіщо це змінюється. Важливість цього моменту добре пояснює розробник Петер Хуттерер (Peter Hutterer) у своєму пості. Ось ключова цитата з нього: Витрачати час на відновлення контексту створення коду надто дорого. Не можна повністю уникнути цього, але ми повинні мінімізувати такі витрати ресурсів. Правильні описи коммітів зменшують потребу відновлювати контекст.Зрештою, за описами коммітів можна зрозуміти, наскільки добре програміст працює в команді. Якщо ви не замислювалися, навіщо потрібні правильні описи коммітів, то, напевно, ви не дуже часто користувалися командою git log. історія залишається безладною та незручною, тому що розробники не користуються їй і не дбають про коректність описів коммітів. Але правильно оформлена історія коммітів - корисна і зручна річ. ній можна самостійно, не залучаючи до цього завдання авторів інших комітів. отримуєте можливість зрозуміти, чому було внесено ті чи інші зміни до коду кілька місяців чи років тому. У довгостроковій перспективі успіх проекту залежить від того, наскільки просто його підтримувати. Коміти може здатися незручністю або зайвою тратою часу. продуктивність команди і навіть привід для гордості. Ця стаття про те, як правильно складати описи коммітів. Це простий спосіб зробити історію змін репозиторію читабельною та інформативною. У більшості мов програмування є угоди щодо стилю написання коду, включаючи іменування, форматування тощо. Звичайно, існують різні підходи до вирішення тих чи інших завдань. Але більшість програмістів впевнені, що краще вибрати одну систему і слідувати їй, ніж працювати без угод і стикатися з хаосом, який з'являється, коли кожен розробник пише код без системи. Команді розробників також варто дотримуватись угод при роботі з репозиторіями в цілому та формуванні історії змін зокрема. Угода має стосуватися щонайменше трьох базових речей: У цей пункт входять синтаксис розмітки, правила перенесення, граматика, пунктуація, використання великих і малих літер. Докладно опишіть ці моменти і зробіть це якнайпростіше, щоб уникнути непорозуміння. Завдяки цьому ви отримаєте історію змін, яку не тільки приємно читати, але яку ще й справді регулярно читають розробники. Контент Що слід писати в описі комміту? Чого в ньому не повинно бути? Метадані Як потрібно відзначати ID issue, номери пулреквестів тощо? На щастя, є загальноприйняті угоди щодо того, якими мають бути описи коммітів. Деякі з них частково пов'язані з тим, як працюють ті чи інші команди Git. Тобто вам не доведеться вигадувати щось самостійно. Дотримуйтесь наведених нижче семи правил, і ви будете комітити як професіонал. Уривок з довідкових матеріалів про git commit: Хоча це і не обов'язкова вимога, рекомендується починати опис комміту з рядка довжиною до 50 символів, який узагальнює зміни. За нею має слідувати порожній рядок, а потім детальніший опис комміту.Текст до порожнього рядка – це заголовок опису комміту, він може використовуватись у різних командах Git. Наприклад, Git-format-patch(1) перетворює коміт на електронний лист, у темі якого використовується заголовок опису, а в тілі - сам опис. По-перше, не кожен коміт повинен мати заголовок та опис. Іноді можна обмежитись одним рядком, якщо зміни дуже прості. У разі додаткова інформація не потрібна. Якщо комусь захочеться дізнатися, які саме помилки були виправлені, це можна зробити за допомогою команди git show, git diff або git log-p. Якщо ви робите подібний коміт, зручно скористатися опцією -m у git commit: А якщо коміт вимагає додаткового пояснення, яке допоможе іншим розробникам одержати контекст, потрібно робити докладний опис. Детальні описи коммітів із заголовком та тілом незручно писати за допомогою опції -m у командному рядку. В цьому випадку краще робити опис комміту в редакторі. Якщо ви ще не налаштували редактор для роботи з Git, прочитайте цей розділ документації та зверніть увагу на наш курс «Налаштування оточення». У будь-якому випадку відокремлювати заголовок від тіла описи корисно. Перегляньте повний запис у журналі змін. А тепер виведемо лише заголовок за допомогою git log --oneline: Або за допомогою команди git shortlog виведемо згруповані за авторами комміти.Тут знову виводиться лише заголовок опису: Git має багато інших ситуацій, в яких в описі комміту важливо мати заголовок і тіло. Але в жодній ситуації це не працює, якщо між заголовком та тілом опису немає порожнього рядка. Це не тверде обмеження, а практично корисна рекомендація. Дотримання цього правила гарантує читабельність заголовка. Також вона змушує автора комміту замислитися та описати зміни максимально коротко. Корисна порада: якщо вам важко коротко описати комміт, це може говорити про те, що ви вносите занадто багато змін за один раз. Намагайтеся робити невеликі комміти. Інтерфейс користувача GitHub враховує ці угоди. Він застерігає вас, якщо довжина заголовка перевищує 50 символів. А якщо заголовок перевищує 72 символи, він обрізається. Тому намагайтеся вкластися в 50 символів, а 72 символи вважайте червоною межею. Це дуже просте правило: завжди пишіть заголовок опису з великої літери. Правильний приклад: Це ще одне просте правило: наприкінці заголовка крапка не ставиться. До речі, зайві знаки пунктуації можуть завадити вам вкластися в ліміт довжини 50 символів, про який йшлося вище. Правильний приклад: Якщо ви не знаєте, що таке наказовий спосіб, думайте про це так: заголовок повинен бути схожим на команду або інструкцію. Ось приклади: Усі сім правил із цієї статті сформульовані у наказовому способі.Наприклад, «не ставте крапку в кінці заголовка», «пишіть заголовок з великої літери». Наказовий спосіб може здатися грубим, тому ми не дуже часто використовуємо його у повсякденному житті. Але воно добре підходить для заголовків в описах коммітів. До речі, Git сам використовує наказовий спосіб, коли робить комміти від вашого імені. Наприклад, при використанні команди git merge автоматично створюється таке повідомлення: А ось повідомлення, яке створюється під час використання команди git revert : Ще один приклад - повідомлення, яке створюється, коли ви натискаєте кнопку Merge, щоб прийняти пулреквест: Тому використання наказового способу відповідає загальноприйнятим угодам Git. Ось кілька прикладів заголовків англійською мовою: Наказовий спосіб може здаватися трохи незвичним, оскільки в повсякденному житті ми частіше користуємося дійсним способом. При використанні дійсного способу мова більше схожа на звіт про події, що відбулися. Заголовки описів у дійсному способі виглядають так: Іноді заголовки просто описують зміст коммітів: Щоб раз і назавжди розібратися із заголовками описів коммітів, запам'ятайте правило: хороший заголовок завжди повинен підходити як закінчення такої пропозиції: «If applied, this commit will (ваш заголовок)». Ось кілька прикладів: Зверніть увагу, якщо в заголовку не використовується наказовий спосіб, він не підходить за змістом як закінчення пропозиції: Обов'язково використовувати наказовий спосіб потрібно тільки в заголовку. У тілі опис комміту його можна не використовувати. Git не переносить текст автоматично. Пам'ятайте про це та переносіть рядки вручну. Рекомендується обмежувати довжину рядка 72 символами. Це дозволить Git залишити в тексті потрібні відступи та вкластися у граничну довжину рядка 80 символів. Дотримуватись цього правила допоможе хороший текстовий редактор. Можна легко налаштувати Vim або інший редактор, щоб переносити рядки, коли їх довжина досягає 72 символів. Приклад опису нижче відмінно показує, як правильно пояснювати, що змінилося. Погляньте на зміни та зауважте, скільки часу автор комміту заощадив іншим розробникам за допомогою опису.Він розкрив контекст змін, який, напевно, загубився б без хорошого опису комміту. Зазвичай можна не писати, як саме зроблено зміни. Якщо код настільки складний, що потребує додаткових пояснень, їх можна зробити у коментарях. Сфокусуйтеся на поясненні причин змін - на тому, як все працювало до змін і що тут було не так, і на тому, як воно зараз працює. У майбутньому інші мейнтенери подякують вам за це, і, можливо, одним із них ви будете! Використовуйте командний рядок — на те є стільки причин, скільки команд у Git. Командний рядок дуже потужний інструмент, як і IDE, але вони хороші кожен по-своєму. Коли потрібно використовувати Git на повну котушку, командний рядок поза конкуренцією. Пам'ятайте про автодоповнення, така функція є і Bash, і Zsh, і Powershell. Автодоповнення позбавляє вас необхідності запам'ятовувати повні команди. Вивчіть Git та командний рядок на Хекслеті У нас є курс Git і курс з основ командного рядка. Зареєстровані користувачі можуть пройти їх безкоштовно. Інші безкоштовні курси можна знайти за посиланням. Її можна безкоштовно завантажити за посиланням.Як правильно коментувати коміти: поради щодо складання хороших повідомлень
Сервіс забезпечує надійний захист ваших веб-ресурсів: моніторинг доступності сайту, контроль за валідністю сертифікатів, а також можливість збирати та аналізувати логи роботи сервера. My-Sites-Guard.com - все для збереження вашого сайту та спокою в роботі!Як скласти гарне повідомлення до комміту?
Часті помилки у повідомленнях коммітів та як їх уникати
Практика: приклади хороших повідомлень для різних типів змін
Коли ви додаєте нову функцію, важливо не просто назвати її, але й пояснити, для чого вона призначена. Приклад: "Додати функцію завантаження профілю користувача для мобільного додатка. Функція дозволяє користувачам завантажувати та змінювати профільні зображення."
Якщо ви виправляєте помилку, уточніть, де вона виникла і як вплинула на роботу коду. Приклад: "Виправити помилку відображення карток продуктів на головній сторінці. Баг викликав некоректне відображення карток зі збільшенням кількості товарів."
При зміні структури коду важливо вказати, що ви не змінювали його поведінку, а лише робили його зручнішим для роботи. Приклад: "Рефакторинг функції обробки замовлень для покращення читання та підвищення продуктивності. Зміни стосуються внутрішньої логіки обробки даних."
Якщо ви вносите зміни до документації, обов'язково вкажіть, що змінилося. Приклад: "Додати опис нового API до документації. Опис включає приклади використання та основні параметри запиту."
Під час оновлення залежностей завжди вказуйте версію та причину оновлення. Приклад: "Оновити бібліотеку jQuery до версії 3.5.1 для підвищення безпеки та виправлення вразливостей."DmitriiNazimov / commitConvention.md
Як писати коміти
Джерела
Шаблон комміту
Приклад комміту
//header chore: drop Node 6 from testing matrix //body see the issue for details on the typs fixed //footer BREAKING CHANGE: dropping Node 6, який з'являється наприкінці життя в квітні 2011 року #12
Приклади заголовків коммітів
Змінений рендер метод в блокі
refactor: Changed render method in Block
refactor(Block.ts): update render method
Декілька коротких правил
Як писати коментар при Pull Request
docs(readme.md): add documentation o project (#3) * docs(workFlow.md): fix name of developing branch * chore(package.json): add commitlint to devDependencies Some extra notes.
Плагін VS Code
Тип комміту
BREAKING CHANGE (критичні зміни)
Зачісуємо комміти
Як правильно складати описи коммітів і чому це важливо
$ git log --oneline
-5
--author cbeams --before
"Fri Mar 26 2009" e5f4b49 Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. Classloader hacking causas subtle downstream ефекти, breaking unrelated tests. The test Метод є невпинним, але повинен тільки йти на автоматичному базі для довкілля CGLIB не має попереднього класифікації, і не слід ходити як частина автоматизованої будівлі. 2db0f12 fixed two build-breaking issues: + reverted ClassMetadataReadingVisitor to revision 794 + eliminated ConfigurationPostProcessorTests until further investigation determines why it causas downstream tests to fail (such as the seemingly unrelated ClassPathXmlApplicationContextTests) 147709f Tweaks to package-info.java files 22b25e0 Уніфікований Util and MutableAnnotationUtils classes in existing AsmUtils 7f96f57 polishing
$ git log --oneline
-5
--author pwebb --before
"Sat Aug 30 2014" 5ba3db6 Fix failing CompositePropertySourceТести 84564a0 Rework @PropertySource early parsing logic e142fd1 Add tests for ImportSelector meta-data 887815f Update docbook dependency and generate epub ac8326d Polish mockito usage
Сім правил доброго опису комміту
Правило 1: залишайте порожній рядок між заголовком та описом
in introduction to user guide $ git commit -m
"Fix typo в програмі інсталяції для користувача"
(causing its deresolution) і turns it back вto chess game. $ git log commit 42e769bdf4894310333942ffc5a15151222a87be Автор: Kevin Flynn Date: Fri Jan 01 00:00:00 1982 -0200 Derezz master control program MCP кинувся від біда і хотів стати на світі domination. This commit throws Trons диск у MCP (causing its deresolution) і turns it back вto chess game.
$ git log --oneline 42e769 Derezz master control program
$ git shortlog Kevin Flynn (1): Derezz master control program Alan Bradley (1): Introduce security program "Tron" Ed Dillinger (3): Rename chess program to "MCP" Modify chess program Upgrade chess program Walter Gibbs (1): Introduce protoype chess program
Правило 2: обмежуйте довжину заголовка 50 символами
Правило 3: пишіть заголовок з великої (великої) літери
Правило 4: не ставте крапку наприкінці заголовка опису
Правило 5: використовуйте наказовий спосіб у заголовку
"Add the thing with the stuff" Це reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d. #123 від someuser/somebranch
Правило 6: обмежуйте довжину рядка в тілі опису 72 символами
Правило 7: у тілі опису відповідайте на запитання «що?» і «чому?», а не «як?»
Замість висновку: корисні поради
Полюбіть командний рядок, використовуйте його замість IDE
Прочитайте книгу Pro Git