پرش به محتوای اصلی

راهنمای سازنده‌ی پیام کامیت

زمان مطالعه: ۲ دقیقه

این ابزار چیست؟

پیام کامیت خوب به هم‌تیمی‌ها، و به خود شما چند ماه بعد، می‌گوید هر تغییر چه بود و چرا انجام شد. قالب Conventional Commits این پیام‌ها را یکدست می‌کند: نوع تغییر، دامنه‌ی اختیاری و یک توضیح کوتاه، مثل fix(parser): handle empty input. ابزارهایی مثل semantic-release و changelog‌سازها از همین قالب نسخه‌ی بعدی و فهرست تغییرات را می‌سازند.

این ابزار پیام را مرحله‌به‌مرحله می‌سازد، بدنه را در ۷۲ نویسه می‌شکند، پاورقی‌هایی مثل Refs و Co-authored-by را اضافه می‌کند، پیام آماده را بررسی می‌کند و یک راهنمای کوتاه از دستورهای رایج git هم دارد. همه‌چیز در مرورگر شما انجام می‌شود.

گام‌به‌گام

  1. نوع تغییر را انتخاب کنید

    در «ساخت پیام» نوع را از میان feat، fix، docs، refactor و بقیه بردارید و در صورت نیاز «دامنه (اختیاری)» را بنویسید، مثلاً auth.

  2. توضیح کوتاه را بنویسید

    در «توضیح کوتاه» با فعل امری و بدون نقطه‌ی پایانی بگویید چه کردید؛ طول خط اول در پیش‌نمایش شمرده می‌شود و بهتر است از ۷۲ نویسه نگذرد.

  3. بدنه و پاورقی را اضافه کنید

    دلیل تغییر را در بدنه بنویسید و اگر تغییر ناسازگار است «تغییر ناسازگار» را روشن کنید. پاورقی‌هایی مثل Closes یا Co-authored-by را از «پاورقی‌ها» اضافه کنید.

  4. پیام آماده را بررسی کنید

    در «بررسی پیام» یک پیام موجود را بچسبانید تا ایرادهای قالبش با توضیح فارسی گزارش شوند.

نمونه‌های کاربردی

  • ساخت یک پیام رفع اشکال

    نوع fix، دامنه‌ی parser و توضیح کوتاه انگلیسی آماده می‌شوند.

    نتیجه: fix(parser): handle empty input

  • بررسی پیامی بی‌قالب

    پیامی که نوع و دونقطه ندارد، با قالب سازگار نیست.

    Fixed the bug.

    نتیجه: خط اول باید به شکل «نوع(دامنه): توضیح» باشد؛ مثلاً «feat(auth): add login form». دامنه اختیاری است ولی بعد از «:» باید فاصله بیاید.

اشتباه‌های رایج

  • نوشتن چند کار در یک کامیت: «fix login and add dark mode» را دو کامیت کنید تا هر کدام را بتوان جدا بازگرداند.
  • توضیح بی‌معنا مثل update یا changes: خواننده باید بی‌آنکه تغییرها را باز کند بفهمد چه شده است.
  • پنهان کردن تغییر ناسازگار: اگر رفتار عمومی عوض شده، علامت ! را بگذارید یا پاورقی BREAKING CHANGE بنویسید تا نسخه‌ی اصلی بالا برود.
  • قاطی کردن زبان‌ها در یک مخزن: اگر تیم پیام‌ها را انگلیسی می‌نویسد، همه را انگلیسی نگه دارید تا جست‌وجو و ابزارها درست کار کنند.

نوع کامیت و نسخه‌ی بعدی

در نسخه‌گذاری معنایی، کامیت fix نسخه‌ی PATCH را بالا می‌برد، feat نسخه‌ی MINOR را و هر کامیتی که تغییر ناسازگار داشته باشد نسخه‌ی MAJOR را. نوع‌های دیگر مثل docs و chore به‌تنهایی نسخه را عوض نمی‌کنند.

خط اول کوتاه و بدنه‌ی پیچیده‌شده در ۷۲ نویسه باعث می‌شود پیام در ترمینال، git log و رابط‌های وب بدون شکستن نامرتب خوانده شود.

پرسش‌های متداول

Conventional Commits چیست و چرا مفید است؟
قالبی ساده برای پیام کامیت است: «نوع(دامنه): توضیح کوتاه». با این قالب می‌توان تاریخچه را خواناتر کرد، فایل تغییرات (changelog) را خودکار ساخت و شماره‌ی نسخه را بر اساس نوع تغییرها تعیین کرد.
کامیت‌ام را فارسی بنویسم یا انگلیسی؟
نوع و دامنه باید انگلیسی و کوچک باشند تا ابزارها بفهمند؛ توضیح کوتاه می‌تواند فارسی باشد. مهم این است که تیم شما یک زبان را یکدست رعایت کند.
آیا پیام من به جایی فرستاده می‌شود؟
خیر. ساخت و بررسی پیام کاملاً در مرورگر شما انجام می‌شود.

ابزارهای مرتبط