Рекомендації Git¶

Налаштуйте свій git¶

Базуючись на досвіді предків та усній традиції, наступні речі значною мірою допомагають зробити ваші зобов’язання більш корисними:

Обов’язково визначте як user.email, так і user.name у вашій локальній конфігурації git
```
git config --global <var> <value>
```
Обов’язково додайте своє повне ім’я у свій профіль Github тут. Будь ласка, насолоджуйтесь і додайте свою команду, аватар, улюблену цитату тощо ;-)

Структура повідомлення фіксації¶

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

[TAG] module: describe your change in a short sentence (ideally < 50 chars)

Long version of the change description, including the rationale for the change,
or a summary of the feature being introduced.

Please spend a lot more time describing WHY the change is being done rather
than WHAT is being changed. This is usually easy to grasp by actually reading
the diff. WHAT should be explained only if there are technical choices
or decision involved. In that case explain WHY this decision was taken.

End the message with references, such as task or bug numbers, PR numbers, and
OPW tickets, following the suggested format:
task-123 (related to task)
Fixes #123  (close related issue on Github)
Closes #123  (close related PR on Github)
opw-123 (related to ticket)

Тег і назва модуля¶

Теги використовуються для префіксу вашого коміту. Вони мають бути одним із наведених нижче

[FIX] для виправлення помилок: переважно використовується в стабільній версії, але також діє, якщо ви виправляєте нещодавню помилку у версії для розробки;
[REF] для рефакторингу: коли функція сильно переписана;
[ADD] для додавання нових модулів;
[REM] для видалення ресурсів: видалення мертвого коду, видалення представлень, видалення модулів, …;
[REV] для повернення комітів: якщо коміт спричиняє проблеми або небажаний, його повертають за допомогою цього тегу;
[MOV] для переміщення файлів: використовуйте git move і не змінюйте вміст переміщеного файлу, інакше Git може втратити відстеження та історію файлу; також використовується при переміщенні коду з одного файлу в інший;
[REL] для фіксації випуску: нові основні або другорядні стабільні версії;
[IMP] для покращень: більшість змін, зроблених у версії для розробки, є поступовими вдосконаленнями, не пов’язаними з іншим тегом;
[MERGE] для комітів злиття: використовується в переданому порті виправлень помилок, а також як основний коміт для функції, що включає кілька окремих комітів;
[CLA] для підписання Ліцензії окремого учасника Odoo;
[I18N] для змін у файлах перекладу;
[PERF] for performance patches;

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

Закріпити заголовок повідомлення¶

Після тегу та назви модуля йде значущий заголовок повідомлення коміту. Воно має бути зрозумілим і містити причину зміни. Не використовуйте окремі слова, як-от «bugfix» або «improvements». Спробуйте обмежити довжину заголовка приблизно 50 символами для зручності читання.

Заголовок повідомлення про фіксацію має становити дійсне речення після того, як його об’єднано з if applied, this commit will <header>. Наприклад, [IMP] base: prevent to archive users linked to active partners, є правильним, оскільки створює дійсне речення if applied, this commit will prevent users to archive....

Повний опис повідомлення коміту¶

В описі повідомлення вкажіть частину коду, на яку вплинули ваші зміни (назва модуля, бібліотека, трансверсальний об’єкт, …) і опис змін.

Спочатку поясніть, ЧОМУ ви змінюєте код. Якщо хтось повернеться до вашого коміту приблизно через 4 десятиліття (або 3 дні), важливо, чому ви це зробили. Це мета змін.

Те, що ви зробили, можна знайти в самому коміті. Якщо були задіяні деякі технічні рішення, було б гарною ідеєю пояснити це також у повідомленні коміту після пояснення чому. До речі, для розробників Odoo R&D «команда PO попросила мене зробити це» не є дійсною причиною.

Будь ласка, уникайте комітів, які одночасно впливають на кілька модулів. Спробуйте розділити на різні коміти, де вражені модулі відрізняються. Це буде корисно, якщо нам потрібно скасувати зміни в певному модулі окремо.

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

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

Якщо ви розробник Odoo R&D, ЧОМУ має бути метою завдання, над яким ви працюєте. Повні специфікації становлять ядро повідомлення коміту. Якщо ви працюєте над завданням, яке не має мети та специфікацій, подумайте про те, щоб уточнити їх, перш ніж продовжувати.

Нарешті, ось кілька прикладів правильних повідомлень комітів:

[REF] models: use `parent_path` to implement parent_store

 This replaces the former modified preorder tree traversal (MPTT) with the
 fields `parent_left`/`parent_right`[...]

[FIX] account: remove frenglish

 [...]

 Closes #22793
 Fixes #22769

[FIX] website: remove unused alert div, fixes look of input-group-btn

 Bootstrap's CSS depends on the input-group-btn
 element being the first/last child of its parent.
 This was not the case because of the invisible
 and useless alert.

Примітка

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

Edit on GitHub