چگونه Commit های بهتری بنویسیم؟

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

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

آیا تا به حال به این فکر کرده اید که چگونه می توانید پیام های Git commit خود را بهبود بخشید؟ این راهنما مراحلی را برای ارتقای پیام‌های commit که می‌توانید از امروز شروع کنید، تشریح می‌کند.

این مقاله فرض می کند که شما از قبل گردش کار یا همان Workflow پایه Git را درک کرده اید. اگر نه، پیشنهاد می کنم مقاله  Git  چیست را مطالعه کنید.

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

فکر می‌کنم از لحظه‌ای که کار در تیم‌ها را شروع می‌کنید، git وارد یک قلمرو کاملاً دیگر می‌شود. جریان‌ها و روش‌های بسیار جالبی وجود دارد که افراد می‌توانند کد را commit کنند، کد به اشتراک بگذارند، و کد را به منبع باز یا منبع بسته به مخزن شما اضافه کنندو

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

من شما را به چالش می کشم تا یک پروژه شخصی یا هر repository دیگری برای آن موضوع باز کنید و git log را برای مشاهده لیستی از پیام های commit قدیمی اجرا کنید. اکثریت قریب به اتفاق ما که آموزش‌ها را اجرا کرده‌ایم یا اصلاحات سریع انجام داده‌ایم، می‌گوییم "بله... من مطلقاً نمی‌دانم منظورم از Fix Style" که 6 ماه پیش انجام دادم چیست."

شاید شما در یک محیط حرفه ای با کد مواجه شده اید که هیچ ایده ای از وجود آن ندارید و نمی دانید دقیقا دارد چه کاری را انجام می دهد. شما بدون کامنت های کد یا سابقه قابل ردیابی در تاریکی رها شده اید، و حتی به این فکر کرده اید که "اگر این خط را حذف کنم، چه شانسی دارد که همه چیز را خراب کند؟"

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

همکاری و ارتباطات در تیم های مهندسی از اهمیت بالایی برخوردار است. پیام commit Git نمونه بارز این است. من به شدت پیشنهاد می‌کنم اگر قبلاً آن را ندارید، یک کنوانسیون برای پیام‌های commit در تیم خود تنظیم کنید.

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

به صورت پایه به صورت زیر می باشد:

git commit -m <message>

و به صورت پیشرفته و بهتر به صورت زیر :

git commit -m <title> -m <description>

5 گام برای نوشتن پیام های commit بهتر

بیایید دستورالعمل های پیشنهادی را خلاصه کنیم:

1.حروف بزرگ و نقطه گذاری: کلمه اول را با حروف بزرگ بنویسید و به علامت گذاری ختم نشود. اگر از Commit های معمولی استفاده می کنید، به یاد داشته باشید که از تمام حروف کوچک استفاده کنید.
2. حالت: از حالت امری در خط موضوع استفاده کنید. مثال “Add fix for dark mode toggle state” اضافه کنید. حالت امری به لحنی که شما سفارش یا درخواست می دهید می دهد.
3. Type of Commit: نوع commit را مشخص کنید. توصیه می شود و حتی می تواند مفیدتر باشد که مجموعه ای ثابت از کلمات برای توصیف تغییرات خود داشته باشید. به عنوان مثال: رفع اشکال، به روز رسانی، Refactor، Bump و غیره
4. طول: خط اول در حالت ایده آل نباید بیشتر از 50 کاراکتر باشد و بدنه باید به 72 کاراکتر محدود شود.
5. محتوا: مستقیم باشید، سعی کنید کلمات و عبارات پرکننده را در این جملات حذف کنید (مثال: هر چند، شاید، به نظر من، نوعی). مثل یک روزنامه نگار فکر کنید.

چگونه خبرنگار درونی خود را پیدا کنید

من هرگز فکر نمی‌کردم که رشته خبرنگاری برای آینده شغلی من به عنوان یک مهندس نرم‌افزار مفید باشد، اما اینجا هستیم!

روزنامه نگاران و نویسندگان از خود سوالاتی می پرسند تا اطمینان حاصل کنند که مقاله آنها مفصل، ساده است و به همه سؤالات خواننده پاسخ می دهد.

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

برای رسیدن به commit ها متفکرانه، موارد زیر را در نظر بگیرید:

1. چرا این تغییرات را انجام دادم؟
2. تغییرات من چه تاثیری داشته است؟
3. چرا تغییر مورد نیاز بود؟
4. تغییرات در ارجاع به چیست؟
 

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

انتظار نداشته باشید که کد خود توضیحی باشد. این شبیه به نکته بالا است.

ممکن است برای شما، برنامه نویس، بدیهی به نظر برسد، اگر چیزی مانند استایل های CSS را به روز می کنید، زیرا بصری است. ممکن است اطلاعات دقیقی در مورد اینکه چرا در آن زمان به این تغییرات نیاز بود، داشته باشید، اما بعید است که بعداً به خاطر بیاورید که چرا این صدها درخواست را انجام دادید.

دلیل ایجاد این تغییر را روشن کنید و توجه داشته باشید که آیا ممکن است برای عملکرد بسیار مهم باشد یا خیر.

تفاوت ها را در زیر ببینید:

1. git commit -m 'Add margin'

2. git commit -m 'Add margin to nav items to prevent them from overlapping the logo'

واضح است که کدام یک از اینها برای خوانندگان آینده مفیدتر است.

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

در فیلمسازی، اغلب با استفاده از تصاویر بصری به عنوان رسانه ارتباطی در مقایسه با توضیح شفاهی آنچه در حال رخ دادن است، نقل می‌شود: «نشان بده، نگو».

در مورد ما، «بگو، [فقط] نشان نده» – اگرچه ما برخی از تصاویر را در اختیار داریم، مانند مرورگر، اما بیشتر جزئیات از خواندن کد فیزیکی ناشی می‌شوند.

اگر کاربر VSCode هستید، افزونه Git Blame را دانلود کنید. این نمونه بارز برای زمانی است که پیام های commit مفید برای توسعه دهندگان آینده مفید هستند.

این افزونه شخصی که تغییر را انجام داده است، تاریخ تغییرات و همچنین پیام commit که به صورت درون خطی نظر داده شده است را فهرست می کند.

تصور کنید که این کار چقدر می تواند در عیب یابی یک اشکال یا تغییرات ردیابی عقب انجام شده مفید باشد. از دیگر موارد افتخاری برای مشاهده اطلاعات تاریخی Git می‌توان به Git History و GitLens اشاره کرد.

commit های مروسم

اکنون که ساختار یک commit اساسی و یک پیام commit خوب را پوشش داده‌ایم، می‌خواهم برای کمک به ارائه جزئیاتی در مورد ایجاد پیام‌های commit جامد، Conventional Commits را معرفی کنم.

در D2iQ، ما از Conventional Commit استفاده می کنیم که یک تمرین عالی در بین تیم های مهندسی است. Conventional Commit یک قرارداد قالب‌بندی است که مجموعه‌ای از قوانین را برای فرمول‌بندی یک ساختار پیام commit ثابت مانند زیر ارائه می‌کند:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

نوع commit می تواند شامل موارد زیر باشد:

feat - یک ویژگی جدید با تغییرات معرفی شده است
fix - رفع اشکال رخ داده است
chore – تغییراتی که به یک اصلاح یا ویژگی مربوط نمی شوند و فایل های src یا تست را تغییر نمی دهند (مثلاً به روز رسانی وابستگی ها)
refactor – کد بازسازی شده که نه باگ را برطرف می کند و نه ویژگی اضافه می کند
docs - به روز رسانی برای اسناد مانند README یا سایر فایل های علامت گذاری
style – تغییراتی که بر معنای کد تأثیر نمی‌گذارد، احتمالاً مربوط به قالب‌بندی کد مانند فاصله سفید، نیمه ویرگول‌های از دست رفته و غیره است.
test – شامل تست های جدید یا تصحیح تست های قبلی
perf - بهبود عملکرد
ci - ادغام پیوسته مرتبط
build – تغییراتی که بر سیستم ساخت یا وابستگی های خارجی تأثیر می گذارد
revert - یک commit قبلی را برمی گرداند

خط موضوع نوع commit باید تماماً با حروف کوچک با محدودیت کاراکتر باشد تا توصیفات مختصر را تشویق کند.

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

همچنین مکان خوبی برای استفاده از <BREAKING CHANGE: description> برای یادداشت دلیل تغییر شکست در commit است.

footer نیز اختیاری است. ما از footer برای پیوند دادن داستان JIRA استفاده می کنیم که با این تغییرات بسته می شود، به عنوان مثال: <D2IQ-JIRA #> را می بندد.

نمونه کامل commit های مرسوم

fix: fix foo to enable bar

This fixes the broken behavior of the component by doing xyz. 

BREAKING CHANGE
Before this fix foo wasn't enabled at all, behavior changes from <old> to <new>

Closes D2IQ-12345

برای اطمینان از اینکه این قراردادهای committing در بین توسعه‌دهندگان ثابت می‌مانند، می‌توان پیش از اعمال تغییرات به بالا، commit message linting را پیکربندی کرد. Commitizen یک ابزار عالی برای اجرای استانداردها، همگام سازی نسخه های معنایی، همراه با سایر ویژگی های مفید است.

برای کمک به پذیرش این کنوانسیون‌ها، گنجاندن دستورالعمل‌هایی برای commit ها در یک فایل علامت‌گذاری مشارکتی یا README در پروژه‌های خود مفید است.

Conventional Commit به ویژه با نسخه‌سازی معنایی خوب کار می‌کند که در آن انواع commit می‌توانند نسخه مناسب را برای انتشار به‌روزرسانی کنند.

مقایسه پیام های Commit

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

موارد زیر خوب هستند:

feat: improve performance with lazy load implementation for images
chore: update npm dependency to latest version
Fix bug preventing users from submitting the subscribe form
Update incorrect client phone number within footer body per client request

و این موارد بد هستند :

fixed bug on landing page
Changed style
oops
I think I fixed it this time?
empty commit messages

نکات بیشتر برای نوشتن commit ها

پیروی از بهترین شیوه های استاندارد، کیفیت کلی سابقه commit شما را افزایش می دهد. پایبندی به قراردادهایی مانند Conventional Commits فرآیند را ساده می کند و به نسخه خودکار کمک می کند.

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

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

نسخه سازی و برچسب گذاری
پیاده‌سازی شیوه‌های نسخه‌سازی و برچسب‌گذاری لایه‌ای از سازمان را به تاریخچه commit شما اضافه می‌کند. این امر به ویژه برای مدیران پروژه و مشارکت کنندگانی که روند تکامل پروژه را دنبال می کنند بسیار ارزشمند است.

ابزارهایی برای commit ها بهتر
چندین ابزار می توانند به نوشتن commit ها بهتر کمک کنند. از الگوهای پیام commit گرفته تا ابزارهای linting، گنجاندن آنها در گردش کار شما می تواند فرآیند commit را ساده کرده و کیفیت پیام های شما را افزایش دهد.

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

نتیجه

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

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

در این مقاله، چند تاکتیک برای ارتقاء سطح پیام های commit خود را یاد گرفتیم. فکر می کنید این تکنیک ها چگونه می توانند commit ها شما را بهبود بخشند؟

امیدوارم چیز جدیدی یاد گرفته باشید.