راهنمایی‌های 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] for moving files: use git move and do not change content of moved file otherwise Git may loose track and history of the file; also used when moving code from one file to another;
[REL] برای کامیت‌های انتشار: نسخه‌های جدید پایدار بزرگ یا کوچک؛
[IMP] برای بهبودها: بیشتر تغییراتی که در نسخه توسعه انجام می‌شود بهبودهای افزایشی هستند و به تگ دیگری مربوط نمی‌شوند؛
[MERGE] برای کامیت‌های ادغام: برای پورت فوروارد رفع باگ‌ها و همچنین به عنوان کامیت اصلی برای ویژگی‌هایی که شامل چندین کامیت جداگانه هستند استفاده می‌شود؛
[CLA] برای امضای مجوز مشارکت‌کننده فردی اودو؛
[I18N] برای تغییرات در فایل‌های ترجمه؛
بعد از تگ، نام ماژول تغییر یافته می‌آید. از نام فنی استفاده کنید زیرا نام کاربردی ممکن است با گذر زمان تغییر کند. اگر چندین ماژول تغییر کرده‌اند، آنها را لیست کنید یا از تگ مختلف برای اشاره به ماژول‌های مختلف استفاده کنید. مگر اینکه ضروری باشد یا ساده‌تر، از تغییر کد در چندین ماژول در یک کامیت خودداری کنید. درک تاریخچه ماژول ممکن است دشوار شود.
سربرگ پیام کامیت¶
بعد از تگ و نام ماژول، یک سربرگ پیام کامیت معنادار قرار می‌گیرد. باید خود توضیح‌دهنده باشد و دلیل تغییر را شامل شود. از کلمات تک مانند "bugfix" یا "improvements" استفاده نکنید. سعی کنید طول سربرگ را برای خوانایی به حدود ۵۰ کاراکتر محدود کنید.
سربرگ پیام کامیت باید با جمله‌ی اگر اعمال شود، این کامیت <header> انجام خواهد داد یک جمله‌ی معتبر بسازد. برای مثال، [IMP] base: prevent to archive users linked to active partners صحیح است زیرا یک جمله معتبر می‌سازد: اگر اعمال شود، این کامیت کاربران را از بایگانی کردن جلوگیری می‌کند....
توضیحات کامل پیام کامیت¶
در توضیحات پیام، بخشی از کد را که تحت تأثیر تغییرات شما قرار گرفته است (نام ماژول، کتابخانه، شیء عرضی و ...) و توضیح تغییرات را مشخص کنید.
ابتدا توضیح دهید که چرا کد را تغییر می‌دهید. آنچه مهم است اگر کسی پس از چند دهه (یا ۳ روز) به کامیت شما بازگردد، این است که چرا آن را انجام دادید. این هدف تغییر است.
آنچه که انجام دادید را می‌توان در خود کامیت یافت. اگر انتخاب‌های فنی در کار بود، بهتر است که آنها را نیز در پیام کامیت پس از توضیح "چرا" ذکر کنید. برای توسعه‌دهندگان R&D اودو، عبارت "تیم PO از من خواست" یک دلیل معتبر نیست.
لطفاً از کامیت‌هایی که به طور همزمان چندین ماژول را تحت تأثیر قرار می‌دهند خودداری کنید. سعی کنید تغییرات را به کامیت‌های جداگانه تقسیم کنید که ماژول‌های تحت تأثیر متفاوت باشند. این کمک می‌کند اگر نیاز به بازگشت تغییرات در یک ماژول خاص باشد، به راحتی انجام شود.
از اضافه‌گویی کمی نترسید. بیشتر مردم فقط پیام کامیت شما را خواهند دید و هر چیزی که در زندگی انجام داده‌اید را فقط بر اساس آن چند جمله قضاوت خواهند کرد. بدون فشار!
شما چندین ساعت، روز یا هفته روی ویژگی‌های معنادار کار می‌کنید. کمی وقت بگذارید تا آرام شوید و پیام‌های کامیت واضح و قابل‌فهم بنویسید.
اگر شما یک توسعه‌دهنده 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.
توجه
از توضیحات طولانی برای توضیح چرا استفاده کنید، نه چه چیزی، چرا که چه چیزی را می‌توان در تفاوت (diff) مشاهده کرد.