Як писати хороші повідомлення про коміти: практичний посібник Git

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

Нещодавно на Hashnode я запитав: "Яку конвенцію повідомлень про коміти ви використовуєте на роботі?" і я отримав кілька дивовижних відповідей із користувачами, які пояснюють правила, які вони використовують на роботі та для своїх особистих проектів.

Яку домовленість повідомлення коміту ви використовуєте на роботі?

від @hashnode //t.co/HewCBxRCbr

- BOLAJI ✨ (@iambolajiayo) 25 листопада 2019 р

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

PS: Ця стаття була вперше опублікована в моєму блозі тут.

Вступ до контролю версій за допомогою Git

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

На сьогоднішній день Git є найбільш широко використовуваною системою контролю версій у світі. Це розподілений та активно підтримуваний проект з відкритим кодом, який спочатку був розроблений у 2005 році Лінусом Торвальдсом, відомим творцем ядра операційної системи Linux.

Новачок у Git? Ознайомтеся з офіційним посібником із початку роботи або з цим слайдом із минулої бесіди, яку я читав.

Що таке повідомлення коміту?

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

Параметри комітів

Цей параметр встановлює повідомлення коміту.

git add static/admin/config.yml git commit -m "Setup multiple roles for netlify-cms git gateway" 
  • -a або --all

Цей параметр автоматично фіксує всі (включаючи нові) відстежувані, змінені або видалені файли.

git commit -a -m "Add a new role for netlify-cms git gateway" 
  • --замін

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

git add . git commit --amend -m "Update roles for netlify-cms git gateway" 

Чому ви повинні писати хороші повідомлення про коміти?

Ви можете сказати: "Це лише особистий проект". Так, зараз ви працюєте на самоті, але що трапляється, коли ви працюєте з командою або робите внесок у відкритий код?

Добре продумане повідомлення коміту Git - це найкращий спосіб повідомити контекст про зміни іншим розробникам, які працюють над цим проектом, і справді, своєму майбутньому.

Ви коли-небудь пробували запустити git logодин зі своїх старих проектів, щоб побачити "дивні" повідомлення комітів, які ви використовували з моменту його створення? Важко зрозуміти, чому ви внесли деякі зміни в минулому, і ви побажаєте, щоб прочитали цю статтю раніше :).

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

Як писати повідомлення комітів за допомогою Git

Раніше я використовував лише git commit -m "Fix X to allow Y to use Z"для своїх особистих проектів лише тему та без додаткового опису. Це чудово підходить для невеликих і чітких виправлень, таких як git commit -m "Fix typo in README.md, але у випадку більш масштабних змін вам потрібно буде додати деякі додаткові деталі.

Метод редактора

Запустіть git commitбез повідомлення або опції, і він відкриє ваш текстовий редактор за замовчуванням, щоб написати повідомлення про коміт.

Щоб налаштувати редактор "за замовчуванням":

git config --global core.editor nano 

Це налаштувало б Git на використання nano як редактора за замовчуванням. Замініть "nano" на "emacs", "vim" або як завгодно.

У відкритому редакторі перший рядок - це тема (короткий опис), залиште порожній рядок після нього, а все інше - розширений опис (тіло).

Метод командного рядка

git commit -m "Subject" -m "Description..." 

Перший -mваріант - це тема (короткий опис), а наступний - розширений опис (основний текст).

Як писати хороші повідомлення про коміти

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

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

Обов’язково перегляньте цю тему щодо неймовірних конвенцій про повідомлення комітів або додайте свою, щоб допомогти комусь прийняти рішення.

Ось чудовий шаблон хорошого повідомлення коміту, спочатку написаного Тімом Попом

Capitalized, short (50 chars or less) summary More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together. Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert. Further paragraphs come after blank lines. - Bullet points are okay, too - Typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between, but conventions vary here - Use a hanging indent If you use an issue tracker, add a reference(s) to them at the bottom, like so: Resolves: #123 

Виглядає чудово, правда? Ось як ви також можете зробити своє чудовим:

  1. Вкажіть тип коміту:
  • подвиг: нова функція, яку ви додаєте до певної програми
  • fix: A bug fix
  • style: Feature and updates related to styling
  • refactor: Refactoring a specific section of the codebase
  • test: Everything related to testing
  • docs: Everything related to documentation
  • chore: Regular code maintenance.[ You can also use emojis to represent commit types]
  1. Separate the subject from the body with a blank line
  2. Your commit message should not contain any whitespace errors
  3. Remove unnecessary punctuation marks
  4. Do not end the subject line with a period
  5. Capitalize the subject line and each paragraph
  6. Use the imperative mood in the subject line
  7. Use the body to explain what changes you have made and why you made them.
  8. Do not assume the reviewer understands what the original problem was, ensure you add it.
  9. Do not think your code is self-explanatory
  10. Follow the commit convention defined by your team

Conclusion

The most important part of a commit message is that it should be clear and meaningful. In the long run, writing good commit messages shows how much of a collaborator you are. The benefits of writing good commit messages are not only limited to your team, but indeed expand to yourself and future contributors.

Want to learn more about Git and become a professional "version controller"? Check out these excellent resources:

  • //try.github.io/
  • //git-scm.com/book/en/v2
  • //www.git-tower.com/learn/
  • //learngitbranching.js.org/
  • //github.com/commitizen/cz-cli