Оригінальна стаття захищена ліцензією Creative Commons Attribution 4.0 International license.
Автор оригінальної статті: Agis Anastasopoulos.
Переклад українською знаходиться в репозиторії denysdovhan/git-style-guide і постійно доповнюється матеріалами з оригінальної статті.
Це керівництво по розробці з Git навіяне статтею Як додати свої зміни в ядро Linux (How to Get Your Change Into the Linux Kernel), інформацією з сторінок довідки git та інших практик, які популярні серед спільноти.
Гілки
Оберіть коротке та змістовне ім'я:
# добре
$ git checkout -b oauth-migration
# погано - надто абстрактно
$ git checkout -b login_fix
Ідентифікатори завдань із зовнішніх сервісів (напр. GitHub Issue) добре підійдуть в якості назв для гілок. Наприклад:
# GitHub issue #15
$ git checkout -b issue-15
Використовуйте дефіс в якості роздільника слів.
Коли кілька людей працюють над тим самим функціоналом, буде зручно, якщо кожен матиме власну персональну гілку та одну спільну гілку.
Використовуйте таке найменування:
$ git checkout -b feature-a/master # спільна гілка
$ git checkout -b feature-a/maria # Персональна гілка Марії
$ git checkout -b feature-a/nick # Персональна гілка Ніка
Зливайте зміни з персональних гілок в одну спільну гліку (див. "Злиття"). Зрештою, спільна гілка буде злита з "master".
Видаляйте ваші гілки з репозиторію після того, як вони були злиті (якщо немає важливої причини, аби цього не робити).
Порада: Використовуйте команду нижче перебуваючи в "master", щоб вивести злиті гілки:
$ git branch --merged | grep -v "\\*"
Коміти
Кожен коміт повинен містити одну логічну зміну. Не робіть кілька логічних змін в одному коміті. Наприклад, якщо ваш патч виправляє помилку та покращує продуктивність, то краще розбити його на два коміти.
Не розділяйте одну логічну зміну на кілька комітів. Наприклад, реалізація нового функціоналу, та покриття цього функціоналу тестами повинні бути в одному коміті.
Комітьте своєчасно та часто. Маленькі, атомарні коміти легше зрозуміти та скасувати, якщо щось піде не так як слід.
Коміти повинні бути логічно впорядковані. Наприклад, якщо коміт X залежить від зміни в коміті Y, тоді коміт Y повинен бути перед комітом X.
Повідомлення
Для написання повідомлень використовуйте текстовий редактор замість терміналу:
# добре
$ git commit
# погано
$ git commit -m "Quick fix"
Написання повідомленнь в терміналі змушують писати повідомлення довжиною не більше одного рядка, що зазвичай виливається в неінформативні та неоднозначні коміти.
Підсумковий рядок (тобто перший рядок повідомлення) повинен бути описовим та лаконічним. В ідеалі, він не повинен зайняти більш як 50 символів. Він повинен починатись з великої літери і бути написаним в теперішньому часі. В кінці не варто ставити крапку, адже він, в деякій мірі є назвою коміту:
# добре - теперішній час, з великої літери, менш ніж 50 символів
Відмічаємо старі записи застарілими, для попередження помилок при очищенні
# погано
Виправили повідомлення про застарілі ActiveModel::Errors Коли AR були використані всередині Rails.
Після цього слід пропустити один рядок та дати повний опис внесених змін. Він повинен бути обмеженим 72 символами та пояснювати для чого були необхідні внесені зміни, як ці зміни виріщують проблему та які побічні ефекти вони можуть мати.
Також в опис слід включити посилання на пов'язані ресурси (напр. посилання на відповідну сторінку помилки в баг-трекері):
Короткий (50 літер або менше) опис змін.
Більш детальний роз'яснювальний текст, при потребі. Обмежений
72 символами. Часом, перший рядок опису коміту трактується як
тема електронного листа, а решту тексту в якості тіла.
Порожня лінія-роздільник, що розділяє "тему" та "тіло" необхідна,
(якщо тільки ви не пропускаєте "тіло" зовсім), інакше інструменти rebase
можуть помилково сприйняти їх як однин рядок.
Наступні параграфи повинні розділятись порожніми рядками.
- Пункти списку також можна використовувати.
- Використовуйте ненумеровані списки з дефісом, крапкою або зірочкою,
в якості роздільника, відділяючи їх від тексту пробілом.
Між пунктами списку має бути порожній рядок.
Сирець: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
Зрештою, коли писатимете повідомлення до коміту, подумайте про те, що може вам знадобитись через рік після цього коміту.
Якщо коміт A залежить від іншого коміту Б, то цю залежність слід вказати в повідомленні до коміту A. Використовуйте хеші комітів, щоб посилатись на них.
Аналогічно, якщо Коміт A вирішує проблему допущену в коміті Б, це слід згадати в повідомленні до коміту А.
Якщо коміт потрібно додати до іншого коміту, використовуйте прапорці --squash та --fixup:
$ git commit --squash f387cab2
Порада: Використовуйте прапорець --autosquash для переміщення ваших
змін. При цьому відмічені коміти будуть злиті автоматично.
Злиття
Не переписуйте опубліковану історію. Історія репозиторію дуже важлива, адже вона дозволяє зрозуміти що насправді відбулось. Зміна опублікованої історії може обернутись великими проблемами для всіх, хто працює з цим репозиторієм.
Однак, бувають випадки, коли переписування історії цілком обґрунтоване. Це випадки коли:
-
Ви одні працюєте над поточною гілкою і ваш код не проходить рев'ю.
-
Вам потрібно "прибрати" в своїй гілці (напр. об'єднати кілька комітів) та/або перемістити зміни в "master", аби пізніше їх злити.
Це означає, ніколи не переписуйте гілку "master" або інші спеціальні гілки (напр. ті які використовуються на робочому сервері, або моніторяться CI-серверами).
Зберігайте історію чистою та простою. Перед злиттям вашої гілки:
- Переконайтесь, що зміни відповідають цьому керівництву, якщо вони не відповідають, то виправте це (об'єднайте коміти, змініть їх порядок, переформулюйте їх повідомленя та інше.)
- Перемістіть зміни в гілку, в яку їх потрібно внести:
[my-branch] $ git fetch
[my-branch] $ git rebase origin/master
# тільки після цього об'єднуйте
Ці команди створюють гілку, яку можна приєднати в кінець "master", що значно спрощує історію комітів.
Примітка: Цей спосіб краще використовувати в проектах з відносно короткими гілками. В іншому випадку краще було б просто провести злиття гілок.
Якщо ваша гілка включає більш як один коміт, не варто проводити автоматичне зливання (fast-forward):
# добре - коміт зі злиттям буде створено
$ git merge --no-ff my-branch
# погано
$ git merge my-branch
Інше.
Є багато різних способів організації командної роботи і в кожного є свої переваги та недоліки. Який спосіб підійде саме вам, залежить від команди, проекту і процесу розробки.
Це означає, що найважливіше — обрати спосіб організації та дотримуватись його.
Будьте послідовними. Це стосується не лише способу організації, але й таких речей, як повідомлення комітів, назви гілок та тегів. Дотримуйтесь обраного стилю у всьому репозиторії, оскільки це покращує розуміння того, що відбувається в історії, в повідомленнях комітів та в іншому.
Тестуйте перед пушем. Не надсилайте в репозиторій напівготові зміни.
Використовуйте анотовані мітки, щоб відмітити релізи або інші важливі точки в історії змін проекту.
Надавайте перевагу підписаним міткам для особистого використання, наприклад в якості закладок для комітів.
Тримайте ваш локальний та віддалений репозиторій в хорошому стані за допомогою команд:
Ще немає коментарів