Как да напиша добри съобщения за ангажиране: Практическо ръководство за 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. Посочете вида на фиксиране:
  • feat: Новата функция, която добавяте към конкретно приложение
  • 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