پرش به مطلب اصلی

قرارداد پیام‌های Commit

این سند، استاندارد مربوط به نحوه نوشتن پیام‌های Commit در تمامی پروژه‌های شرکت را تعریف می‌کند.

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

رعایت این استاندارد باعث بهبود فرآیندهای Code Review، Debugging، Release Management و آماده‌سازی پروژه‌ها برای CI/CD و Automation خواهد شد.

ساختار استاندارد​

فرمت استاندارد پیام Commit به صورت زیر است:

type:[JIRA-ISSUE-KEY] commit message

نمونه:

feat:[ZIRSAKHT-123] add callback verification

Type (اجباری)​

فیلد type مشخص‌کننده نوع تغییر انجام‌شده در Commit است و باید همیشه مقدار معتبر داشته باشد.

لیست Typeهای مجاز:

Typeتوضیحات
featافزودن قابلیت یا ویژگی جدید
fixرفع باگ یا اصلاح رفتار اشتباه
docsتغییر یا تکمیل مستندات
styleتغییرات ظاهری در کد بدون تغییر در منطق برنامه (مانند Formatting، فاصله‌گذاری یا Lint)
refactorبازنویسی یا بهبود ساختار کد بدون تغییر رفتار موجود
perfبهبود عملکرد و افزایش کارایی سیستم
testافزودن یا اصلاح تست‌ها
buildتغییرات مرتبط با فرآیند Build یا وابستگی‌های پروژه
ciتغییرات مربوط به CI/CD و فرآیندهای استقرار
choreتغییرات نگهداری عمومی پروژه که در دسته‌های دیگر قرار نمی‌گیرند (مانند تنظیمات، Scriptها و Dependencyها)
revertبازگرداندن یک Commit یا تغییر قبلی

JIRA Issue Key​

در صورت مرتبط بودن Commit با یک Task مشخص، JIRA Issue Key باید در پیام Commit درج شود.

قوانین:

  • مقدار JIRA Issue Key باید دقیقاً مطابق Issue مربوطه در JIRA باشد.
  • JIRA Issue Key باید همواره با حروف بزرگ (UPPERCASE) نوشته شود.
نمونه غیرمجاز:
zirsakht-123
نمونه صحیح:
ZIRSAKHT-123

Commit Message​

بخش توضیح Commit باید ویژگی‌های زیر را داشته باشد:

  • به صورت دستوری (Imperative Mood) نوشته شود.
  • در زمان حال (Present Tense) باشد.
  • کوتاه و مشخص باشد.
  • از توضیحات اضافی و غیرضروری خودداری شود.
  • حداکثر طول آن ۷۰ کاراکتر باشد.
نمونه غیرمجاز:
added authentication middleware for user login process
نمونه صحیح:
add authentication middleware

نمونه‌های استاندارد

feat:[ZIRSAKHT-123] add callback verification
fix:[OMRAN-98] resolve refresh token expiration issue
refactor:[SAMPAD-110] extract service from controller
chore:[HAMYAR-44] update docker compose configuration
docs:[OMRAN-31] add authentication guide

Breaking Change​

برای تغییراتی که باعث شکسته شدن سازگاری نسخه‌های قبلی (Backward Compatibility) می‌شوند، باید از علامت ! بعد از Type استفاده شود.

ساختار:
type!:[JIRA-ISSUE-KEY] commit message
نمونه:
feat!:[SAMPAD-200] change authentication strategy

قوانین مهم​

Commit باید بدون مشاهده کد قابل فهم باشد​

پیام Commit باید به تنهایی مفهوم تغییر را منتقل کند.

نمونه غیرمجاز:
fix bug
نمونه صحیح:
fix:[OMRAN-98] prevent login with expired refresh token

هر Commit باید یک تغییر منطقی داشته باشد​

هر Commit باید یک واحد منطقی از تغییرات را شامل شود.

نمونه غیرمجاز:
feat: add login + fix payment bug + update ui
نمونه صحیح:
feat:[HAMYAR-101] add login endpoint
fix:[ZIRSAKHT-102] resolve callback mismatch issue

استفاده از زمان حال (Present Tense)​

پیام Commit باید با فعل زمان حال نوشته شود.

نمونه‌های صحیح:
add
fix
remove
update
نمونه‌های غیرمجاز:
added
fixed
removed
updated

Commit باید کوچک اما معنادار باشد​

  • Commitهای بسیار بزرگ باید به چند Commit کوچک‌تر تقسیم شوند.
  • هر Commit باید یک تغییر مشخص و قابل بررسی را نشان دهد.
  • Commit نباید شامل چند تغییر مستقل و نامرتبط باشد.

نمونه‌های غیرمجاز​

Commit messageهای زیر با استاندارد سازمان مطابقت ندارند:

update code
fix bug
changes
final version
wip
temp fix

WIP Commit (شرایط خاص)​

در شرایطی که نیاز به ذخیره موقت تغییرات نیمه‌کاره وجود دارد، استفاده از Commit با عنوان WIP تنها به صورت موقت مجاز است.

ساختار:

type:[JIRA-ISSUE-KEY][WIP] commit message

نمونه:

feat:[OMRAN-120][WIP] implement login flow

Commitهای WIP:

  • نباید برای Merge Request ارسال شوند.
  • نباید وارد Branchهای main یا develop شوند.
  • باید قبل از ایجاد Merge Request اصلاح یا Squash شوند.

Best Practice تیمی​

برای حفظ کیفیت تاریخچه Git:

  • قبل از Push، Commitها باید توسط توسعه‌دهنده بررسی شوند (Self Review).
  • Commitهای نامناسب یا کم‌ارزش باید قبل از Merge Request اصلاح یا Squash شوند.
  • در فرآیند Release، استفاده از Squash Merge توصیه می‌شود.

جمع‌بندی​

رعایت استاندارد Commit Message باعث می‌شود:

  • تاریخچه Git قابل جستجو و تحلیل باشد.
  • فرآیند Debugging سریع‌تر انجام شود.
  • Code Review ساده‌تر و دقیق‌تر شود.
  • CI/CD و Automation بتوانند بر اساس تغییرات Commitها عملکرد دقیق‌تری داشته باشند.

اگر برای فهم یک Commit نیاز به توضیح اضافی وجود دارد، احتمالاً پیام Commit به اندازه کافی شفاف نوشته نشده است.