چگونه یک پیام Git Commit موثر و مفید بنویسیم

Git به تیم های متنوع و توزیع شده کمک می کند تا روی یک پایگاه کد یکپارچه کار کنند. با این قدرت یک مسئولیت به وجود می آید: ارائه توضیحات خوب از تغییرات خود.

پیام های commit توضیحات کوتاهی از هر commit در یک سیستم کنترل نسخه مانند Git هستند. هنگامی که تغییراتی را در فایل‌های پروژه خود انجام می‌دهید، باید پیامی ارائه دهید که در آن توضیح دهید که چه کاری انجام می‌دهند یا چرا آنها را ایجاد کرده‌اید.

پیام های متعهد به عنوان شکلی از اسناد و ارتباطات عمل می کنند. آنها نقش مهمی در حفظ تاریخچه نسخه واضح و سازمان یافته یک پروژه دارند. یاد بگیرید که چگونه پیام های commit خوب بنویسید و سایر اعضای تیم شما حتی بیشتر از کار شما قدردانی خواهند کرد.

ساختار یک پیام تعهد خوب

یک مثال خوب از یک پیام commit شامل چهار بخش است: Type، Description، Body و Footer.

اینطوری:

<type>: <description>

[optional body]

[optional footer]

تایپ کنید

نوع، نوع تغییر ایجاد شده در commit فعلی را توصیف می کند. شما می توانید از هر سیستمی که برای شرایط شما منطقی است استفاده کنید. به عنوان مثال، در اینجا چند کلمه کلیدی نمونه وجود دارد که می توانید از آنها برای نشان دادن هر نوع تغییر استفاده کنید، در کنار نمونه استفاده:

feat: تغییرات شما یک ویژگی جدید را معرفی می کند.
رفع: شما یک اشکال را رفع می کنید.
refactor: کد refactors تغییر شما بدون رفع باگ یا افزودن ویژگی جدید.
تست: هر گونه تغییر مرتبط با آزمایش را ایجاد می کنید. به عنوان مثال، زمانی که تست هایی را با Jest یا هر چارچوب تست دیگری که انتخاب می کنید می نویسید.
chore: تغییرات غیر مرتبط با یک اصلاح، ویژگی یا آزمایش. به عنوان مثال، به روز رسانی وابستگی ها.
اسناد: زمانی که اسناد را به روز می کنید.
سبک: تغییراتی که بر معنای کد تأثیر نمی گذارد، مانند اضافه کردن فضای خالی، خالی کردن نیم دونقطه و غیره.
perf: تغییرات مربوط به بهبود عملکرد.
build: زمانی که تغییراتی ایجاد می کنید که روی فایل های ساخت تاثیر می گذارد.
ci: تغییرات مربوط به ادغام پیوسته.
revert: هنگام بازگشت به commit قبلی.

مطلب مرتبط: نحوه کلون کردن و اجرای پروژه جنگو به صورت محلی

شرح

“توضیح” یک پیام commit خلاصه ای مختصر و توصیفی از تغییرات ایجاد شده در commit است. این به عنوان عنوانی عمل می کند که ماهیت تعهد را نشان می دهد.

هنگام نوشتن توضیحات، موارد زیر را در نظر داشته باشید:

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

مثلا:

feat: Implement dark mode toggle for home page

این مثال نشان می دهد که چگونه می توانید توضیحاتی را برای یک commit بنویسید که حالت تاریک را پیاده سازی می کند. از نوع feat استفاده می کند زیرا ویژگی جدیدی را معرفی می کند.

بدنه (اختیاری)

بخش بدنه یک پیام commit جزئیات و زمینه بیشتری را در مورد تغییرات ایجاد شده در commit ارائه می دهد. شما همیشه به بدن نیاز نخواهید داشت، اما می‌تواند به ارائه اطلاعات بیشتر، توضیح استدلال تغییر یا توصیف هرگونه ملاحظات فنی کمک کند.

در اینجا مواردی وجود دارد که باید هنگام نوشتن بخش بدن یک پیام commit توجه داشته باشید:

Git هرگز متن را به صورت خودکار بسته بندی نمی کند، بنابراین هنگام نوشتن متن به صورت دستی آن را با 72 کاراکتر بپیچید. این به Git فضای کافی برای تورفتگی متن می دهد و آن را خواناتر می کند.
از بدن برای توضیح اینکه در تغییر چه اتفاقی افتاده، چرا تغییر ایجاد کرده‌اید و استدلال پشت تغییر خود استفاده کنید.
شما باید یک خط خالی بین خط توضیحات و بدنه بگذارید. این به Git اجازه می دهد تا بین آنها تمایز قائل شود.
اگر commit چندین تغییر ایجاد می کند یا بر مناطق مختلف پایگاه کد تأثیر می گذارد، از نقاط یا پاراگراف ها برای شکستن تغییرات استفاده کنید. این خوانایی را بهبود می بخشد و به خوانندگان کمک می کند تا جنبه های مختلف تعهد را درک کنند.

مطلب مرتبط: روش‌های نمونه در مقابل استاتیک در مقابل کلاس در پایتون: تفاوت‌های مهم

مثلا:

feat: Add GitHub as an OAuth provider Integrate GitHub as an OAuth provider to enable seamless authentication with GitHub accounts. - Implement OAuth authentication flow with GitHub API - Configure necessary endpoints and settings for GitHub authentication - Update user interface to include GitHub login option

مثال بالا یک پیام commit خوب Git را برای یک ویژگی نشان می دهد که GitHub را به عنوان یک ارائه دهنده OAuth به برنامه شما اضافه می کند. این پیام commit دارای یک خط خلاصه مختصر (50 کاراکتر یا کمتر)، یک متن توضیحی دقیق تر (حدود 72 کاراکتر) و نقاط گلوله برای اطلاعات بیشتر است.

پاورقی (اختیاری)

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

هنگام ارجاع به مسائل، درخواست های کششی یا سایر موارد مرتبط، از نحو یا قالب مناسب مورد نیاز سیستم ردیابی مسائل پروژه خود استفاده کنید. این تضمین می کند که مراجع به درستی شناسایی و پیوند داده شده اند.

مثلا:

feat: Add GitHub as OAuth provider Integrate GitHub as an OAuth provider to enable seamless authentication with GitHub accounts. - Implement OAuth authentication flow with GitHub API - Configure necessary endpoints and settings for GitHub authentication - Update user interface to include GitHub login option Resolves: #123 See also: #456, #789

پاورقی به موضوع مرتبط شماره 123 اشاره می کند و سایر موضوعات مرتبط شماره 456 و 789 را برای زمینه اضافی ذکر می کند.

مطلب مرتبط: چگونه یک صفحه گسترده اکسل را با پایتون و Openpyxl ویرایش کنیم

افزودن پیام Commit

می‌توانید پیام‌های commit را با استفاده از پرچم -m و به دنبال آن پیام commit که در گیومه قرار دارد بنویسید (اختیاری اما توصیه می‌شود).

پرچم -m برای پیام‌های commit کوتاه، معمولاً شامل نوع و توضیحات، ایده‌آل است.

مثلا:

git commit -m "chore: Change linter to ESlint"

با این حال، زمانی که پیام commit شما به جزئیات بیشتری مانند بدنه و پاورقی نیاز دارد، بهتر است commit را در یک ویرایشگر متن یا IDE بنویسید.

همچنین، می‌توانید پیام‌های commit طولانی را در یک فایل متنی بنویسید و از پرچم –file برای تعیین پیام‌های commit به عنوان محتوای فایل متنی استفاده کنید.

مثلا:

git commit --file commit_message.txt

وقتی دستور بالا را اجرا می کنید، git از محتویات فایل به عنوان پیام commit استفاده می کند.

همچنین می‌توانید به git بگویید ویرایشگر پیش‌فرض شما را باز کند تا پیام طولانی‌تری بنویسد. اگر مجموعه متغیرهای محیطی GIT_EDITOR یا EDITOR را دارید، git آن برنامه را با اجرای دستور commit bare git باز می کند.

چرا باید پیام های تعهدی خوب بنویسید؟

نوشتن پیام های commit خوب برای همکاری موثر و نگهداری کد بسیار مهم است. پیام های واضح و توصیفی به درک، اشکال زدایی و بررسی کد کمک می کنند. آنها حتی می توانند در اسناد پروژه یا یادداشت های انتشار مشارکت کنند.

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