راهنمای Git

Git خود را پیکربندی کنید

بر اساس تجربه پیشینیان و روایت شفاهی، موارد زیر برای مفیدتر کردن commits شما کمک زیادی می‌کنند:

• اطمینان حاصل کنید هر دو user.email و user.name را در git config محلی خود تعریف کنید

  git config --global <var> <value>
  

• اطمینان حاصل کنید نام کامل خود را به پروفایل GitHub خود اینجا اضافه کنید. لطفاً احساس fancy کنید و تیم، avatar، نقل قول مورد علاقه خود و غیره را اضافه کنید ;-)

ساختار پیام کامیت

پیام commit چهار بخش دارد: برچسب، ماژول، توضیحات کوتاه و توضیحات کامل. سعی کنید ساختار ترجیحی را برای پیام‌های commit خود دنبال کنید

[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)

برچسب و نام ماژول

Tags برای پیشوند دادن به commit شما استفاده می‌شوند. آن‌ها باید یکی از موارد زیر باشند

• [FIX] برای اصلاح باگ: عمدتاً در stable version استفاده می‌شود اما اگر در حال اصلاح یک باگ اخیر در نسخه development هستید نیز معتبر است؛

• [REF] برای بازسازی: زمانی که یک ویژگی به‌طور گسترده بازنویسی می‌شود؛

• [ADD] برای افزودن ماژول‌های جدید؛

• [REM] برای حذف resources: حذف dead code، حذف views، حذف modules، ...؛

• [REV] برای revert کردن commits: اگر یک commit مشکلاتی ایجاد می‌کند یا مورد نظر نیست، revert کردن آن با استفاده از این برچسب انجام می‌شود؛

• [MOV] برای جابه‌جا کردن فایل‌ها: از git move استفاده کنید و محتوای فایل جابه‌جاشده را تغییر ندهید در غیر این صورت Git ممکن است track و تاریخچه فایل را از دست بدهد؛ همچنین هنگام جابه‌جا کردن کد از یک فایل به فایل دیگر استفاده می‌شود؛

• [REL] برای کامیت‌های انتشار: نسخه‌های پایدار اصلی یا جزئی جدید؛

• [IMP] برای improvements: بیشتر تغییرات انجام‌شده در نسخه development بهبودهای incremental هستند که به برچسب دیگری مربوط نمی‌شوند؛

• [MERGE] برای merge commits: در forward port اصلاح باگ‌ها استفاده می‌شود اما همچنین به‌عنوان main commit برای ویژگی‌ای که شامل چندین commit جداگانه است؛

• [CLA] برای امضای مجوز مشارکت‌کننده فردی Odoo؛

• [I18N] برای تغییرات در فایل‌های ترجمه؛

• [PERF] برای patchهای کارایی؛

• [CLN] برای پاکسازی کد؛

• [LINT] برای پاس‌های linting؛

بعد از برچسب نام ماژول تغییریافته می‌آید. از نام فنی استفاده کنید زیرا نام functional ممکن است با زمان تغییر کند. اگر چندین ماژول تغییر یافته‌اند، آن‌ها را فهرست کنید یا از various استفاده کنید تا بگویید cross-modules است. مگر اینکه واقعاً ضروری یا آسان‌تر باشد، از تغییر کد در چندین ماژول در یک commit واحد اجتناب کنید. درک تاریخچه ماژول ممکن است دشوار شود.

سربرگ پیام کامیت

بعد از برچسب و نام ماژول، یک سربرگ پیام commit معنادار می‌آید. باید self-explanatory باشد و دلیل پشت تغییر را شامل شود. از کلمات تک‌کلمه‌ای مانند «bugfix» یا «improvements» استفاده نکنید. سعی کنید طول سربرگ را برای خوانایی به حدود 50 کاراکتر محدود کنید.

سربرگ پیام commit باید پس از الحاق با 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....

توضیحات کامل پیام کامیت

در توضیحات پیام، بخشی از کد که توسط تغییرات شما تحت تأثیر قرار گرفته را مشخص کنید (نام ماژول، lib، transversal object، ...) و توصیفی از تغییرات.

ابتدا توضیح دهید چرا کد را تغییر می‌دهید. آنچه مهم است اگر کسی در حدود 4 دهه (یا 3 روز) به commit شما برگردد این است که چرا آن را انجام دادید. این هدف از تغییر است.

آنچه انجام داده‌اید را می‌توان در خود commit یافت. اگر برخی انتخاب‌های فنی درگیر بوده‌اند، ایده خوبی است که آن را نیز در پیام commit پس از why توضیح دهید. برای توسعه‌دهندگان Odoo R&D «PO تیم asked me to do it» یک why معتبر نیست، به‌هرحال.

لطفاً از commit هایی که هم‌زمان بر چندین ماژول تأثیر می‌گذارند اجتناب کنید. سعی کنید به commits مختلف تقسیم کنید جایی که ماژول‌های تحت تأثیر متفاوت هستند. اگر نیاز داشته باشیم تغییرات را در یک ماژول معین به‌طور جداگانه revert کنیم، مفید خواهد بود.

از کمی verbose بودن دریغ نکنید. بیشتر مردم فقط پیام commit شما را خواهند دید و همه چیزی را که در زندگی خود انجام داده‌اید فقط بر اساس آن چند جمله قضاوت خواهند کرد. اصلاً فشاری نیست.

شما چند ساعت، روز یا هفته را صرف کار روی features معنادار می‌کنید. کمی وقت بگذارید تا آرام شوید و پیام‌های commit واضح و قابل فهم بنویسید.

اگر یک توسعه‌دهنده Odoo R&D هستید، WHY باید هدف کاری باشد که روی آن کار می‌کنید. مشخصات کامل، هسته پیام commit را تشکیل می‌دهد. اگر روی کاری کار می‌کنید که فاقد هدف و مشخصات است، لطفاً قبل از ادامه آن‌ها را روشن کنید.

در نهایت، چند مثال از پیام‌های کامیت صحیح:

[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.

توجه

از توضیحات بلند برای توضیح why استفاده کنید نه what، what را می‌توان در diff دید