راهنمایی‌های گیت¶

پیکربندی گیت خود را انجام دهید¶

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

اطمینان حاصل کنید که هم user.email و هم user.name را در تنظیمات محلی گیت خود تعریف کنید.
```
git config --global <var> <value>
```
حتماً نام کامل خود را به پروفایل گیت‌هاب خود در اینجا اضافه کنید. لطفاً حرفه‌ای باشید و تیم خود، تصویر آواتار، نقل‌قول مورد علاقه‌تان و هر چیز دیگری را اضافه کنید ;-)

ساختار پیام تعهد¶

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

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

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

برچسب‌ها برای پیشوند دادن به تعهدات شما استفاده می‌شوند. آنها باید یکی از موارد زیر باشند:

[اصلاح] برای رفع اشکالات: بیشتر در نسخه پایدار استفاده می‌شود اما در صورتی که یک اشکال اخیر در نسخه توسعه را رفع می‌کنید نیز معتبر است؛
[بازنویسی] برای بازسازی: زمانی که یک ویژگی به طور گسترده بازنویسی می‌شود؛
[افزودن] برای افزودن ماژول‌های جدید؛
[حذف] برای حذف منابع: حذف کدهای بلااستفاده، حذف نماها، حذف ماژول‌ها، ...؛
[بازگشت] برای بازگرداندن کامیت‌ها: اگر یک کامیت باعث مشکلاتی شود یا مورد نیاز نباشد، بازگرداندن آن با استفاده از این برچسب انجام می‌شود؛
[جابجایی فایل] برای جابجایی فایل‌ها: از git move استفاده کنید و محتوای فایل جابجا شده را تغییر ندهید، در غیر این صورت Git ممکن است ردگیری و تاریخچه فایل را از دست بدهد؛ همچنین زمانی که کد از یک فایل به فایل دیگر منتقل می‌شود استفاده می‌شود؛
[REL] برای کامیت‌های انتشار: نسخه‌های پایدار جدید اصلی یا فرعی؛
[بهبود] برای بهبودها: بیشتر تغییراتی که در نسخه توسعه انجام شده‌اند، بهبودهای تدریجی هستند و به برچسب دیگری مرتبط نیستند؛
[ادغام] برای کامیت‌های ادغام: استفاده شده در انتقال به جلو برای رفع اشکالات، همچنین به عنوان کامیت اصلی برای ویژگی‌هایی که شامل چندین کامیت جداگانه هستند؛
[CLA] برای امضای مجوز مشارکت‌کننده فردی اودو؛
[I18N] برای تغییرات در فایل‌های ترجمه؛
[PERF] برای وصله‌های عملکرد؛

پس از برچسب، نام ماژول اصلاح‌شده قرار می‌گیرد. از نام فنی استفاده کنید زیرا نام کاربردی ممکن است با گذشت زمان تغییر کند. اگر چندین ماژول اصلاح شده‌اند، آن‌ها را فهرست کنید یا از "متعدد" استفاده کنید تا نشان دهید که تغییرات بین ماژول‌ها انجام شده است. مگر اینکه واقعاً ضروری یا آسان‌تر باشد، از اصلاح کد در چندین ماژول در یک تعهد خودداری کنید. درک تاریخچه ماژول ممکن است دشوار شود.

سرصفحه پیام تعهد¶

پس از برچسب و نام ماژول، یک عنوان پیام تعهد معنادار قرار می‌گیرد. این عنوان باید خود توضیح‌دهنده باشد و دلیل تغییر را شامل شود. از کلمات تک‌واژه‌ای مانند "رفع اشکال" یا "بهبودها" استفاده نکنید. سعی کنید طول عنوان را برای خوانایی حدود ۵۰ کاراکتر محدود کنید.

عنوان پیام تعهد باید یک جمله معتبر ایجاد کند وقتی با «اگر اعمال شود، این تعهد خواهد <عنوان>» ترکیب شود. به عنوان مثال، «[IMP] base: جلوگیری از بایگانی کاربران مرتبط با شرکای فعال» صحیح است زیرا یک جمله معتبر ایجاد می‌کند «اگر اعمال شود، این تعهد کاربران را از بایگانی جلوگیری خواهد کرد...».

توضیحات کامل پیام تعهد¶

در توضیحات پیام، بخش کد تحت تأثیر تغییرات خود را مشخص کنید (نام ماژول، کتابخانه، شیء مشترک، ...) و توضیحی درباره تغییرات ارائه دهید.

ابتدا توضیح دهید چرا کد را تغییر می‌دهید. چیزی که مهم است اگر کسی بعد از حدود چهار دهه (یا ۳ روز) به تعهد شما بازگردد، دلیل این تغییر است. این هدف از تغییر است.

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

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

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

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

اگر شما یک توسعه‌دهنده تحقیق و توسعه Odoo هستید، دلیل انجام وظیفه‌ای که روی آن کار می‌کنید باید هدف اصلی باشد. مشخصات کامل، هسته پیام تعهد را تشکیل می‌دهند. اگر روی وظیفه‌ای کار می‌کنید که فاقد هدف و مشخصات است، لطفاً قبل از ادامه، آنها را روشن کنید.

در نهایت، در اینجا چند نمونه از پیام‌های صحیح تعهد آورده شده است:

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

توجه

از توضیحات طولانی برای توضیح چرا استفاده کنید، نه چیست، زیرا چیست را می‌توان در تفاوت‌ها مشاهده کرد.