```html

راهنمای جامع نوشتن کامیت مسیج (Commit Message) استاندارد در گیت برای توسعه‌دهندگان

چرا نوشتن کامیت مسیج استاندارد اینقدر مهم است؟

در دنیای پرشتاب توسعه نرم‌افزار، گیت (Git) به عنوان یک سیستم کنترل نسخه قدرتمند، ستون فقرات بسیاری از پروژه‌ها، از استارتاپ‌های کوچک گرفته تا شرکت‌های بزرگ فناوری مانند GitHub و GitLab، محسوب می‌شود. اما تنها استفاده از گیت کافی نیست؛ نحوه استفاده از آن، به‌ویژه در مورد پیام‌های کامیت (Commit Message)، نقشی حیاتی در موفقیت یک پروژه و کارایی تیم ایفا می‌کند.

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

یک کامیت مسیج استاندارد و خوش‌نوشته، فراتر از یک یادداشت ساده است؛ این پیام، بخشی از مستندات پروژه شماست که فواید متعددی دارد:

• بهبود همکاری تیمی: وقتی همه اعضای تیم از یک فرمت و زبان مشترک برای ثبت تغییرات استفاده می‌کنند، درک وضعیت پروژه و مشارکت در آن آسان‌تر می‌شود. پیام‌های واضح به توسعه‌دهندگان دیگر اجازه می‌دهد تا به‌سرعت هدف تغییرات شما را درک کنند.
• ردیابی دقیق تغییرات: تاریخچه گیت، حافظه پروژه شماست. کامیت‌های استاندارد، این حافظه را سازمان‌یافته و قابل جستجو نگه می‌دارند. این امر برای عیب‌یابی (debugging)، حسابرسی (auditing) و بازبینی کد (Code Review) بسیار حیاتی است.
• تسهیل فرآیند بازبینی کد (Code Review): یک Code Reviewer می‌تواند با خواندن پیام کامیت، به‌سرعت هدف و دامنه تغییرات را بفهمد و تمرکز خود را بر روی منطق کد بگذارد، نه صرفاً درک اینکه چه کاری انجام شده است.
• مستندسازی خودکار: استانداردهایی مانند Conventional Commits می‌توانند به طور خودکار برای تولید فایل Changelog یا مستندات انتشار (Release Notes) استفاده شوند. این کار زمان زیادی را برای تیم صرفه‌جویی می‌کند.
• پشتیبانی از ابزارهای CI/CD: بسیاری از ابزارهای یکپارچه‌سازی و استقرار پیوسته (CI/CD) از اطلاعات موجود در کامیت مسیج‌ها برای خودکارسازی فرآیندهای انتشار و مدیریت نسخه‌ها استفاده می‌کنند.
• کاهش سردرگمی در پروژه‌های طولانی‌مدت: در پروژه‌هایی که سال‌ها عمر می‌کنند (مانند پروژه‌های زیرساختی که ممکن است 10 تا 15 سال عمر کنند)، کامیت‌های استاندارد به توسعه‌دهندگان جدید یا کسانی که پس از مدتی به پروژه بازمی‌گردند، کمک می‌کنند تا به‌سرعت با تاریخچه و منطق تغییرات آشنا شوند.

ساختار یک کامیت مسیج استاندارد: اجزا و اصول

استانداردها و الگوهای مختلفی برای نوشتن کامیت مسیج وجود دارد، اما اکثر آن‌ها بر یک ساختار کلی تکیه دارند که شامل چند بخش اصلی است. رایج‌ترین و توصیه‌شده‌ترین استاندارد، "Conventional Commits" است که توسط بسیاری از پروژه‌های بزرگ متن‌باز (Open Source) مانند Angular استفاده می‌شود. بیایید اجزای این ساختار را بررسی کنیم:

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

1. هدر (Header): شامل نوع، محدوده (اختیاری) و موضوع.
2. بدنه (Body): توضیحات بیشتر در مورد تغییرات (اختیاری).
3. فوتر (Footer): شامل اطلاعات اضافی مانند تغییرات شکننده (Breaking Changes) یا ارجاع به مسائل (Issues) (اختیاری).

۱. هدر (Header)

هدر، کوتاه‌ترین و مهم‌ترین بخش کامیت مسیج است و باید به‌سرعت هدف تغییر را مشخص کند. این بخش شامل موارد زیر است:

نوع (Type):

نوع کامیت، ماهیت تغییر اعمال‌شده را مشخص می‌کند. استفاده از انواع استاندارد به دسته‌بندی و خوانایی تاریخچه کمک شایانی می‌کند. برخی از رایج‌ترین انواع عبارتند از:

• feat: زمانی که یک قابلیت جدید به پروژه اضافه می‌کنید. (مثال: feat: Add user authentication with JWT)
• fix: زمانی که یک باگ را برطرف می‌کنید. (مثال: fix: Resolve login button alignment issue)
• docs: زمانی که تغییرات فقط مربوط به مستندات (مانند README یا توضیحات کد) است. (مثال: docs: Update installation instructions)
• style: زمانی که تغییرات در کد، بر معنای آن تأثیر نمی‌گذارند؛ مانند قالب‌بندی کد، حذف فضاهای خالی اضافی، یا تنظیم تورفتگی‌ها. (مثال: style: Format code according to Prettier rules)
• refactor: زمانی که کد را بازنویسی می‌کنید بدون اینکه عملکرد یا قابلیت جدیدی اضافه کنید یا باگی را برطرف کنید؛ صرفاً برای بهبود ساختار کد. (مثال: refactor: Extract user service to a separate module)
• test: زمانی که تست‌های جدید اضافه می‌کنید یا تست‌های موجود را بهبود می‌بخشید. (مثال: test: Add unit tests for payment gateway)
• perf: زمانی که تغییراتی برای بهبود عملکرد (Performance) اعمال می‌کنید. (مثال: perf: Optimize database query for user list)
• build: زمانی که تغییرات بر روی سیستم بیلد (Build System)، وابستگی‌های خارجی (External Dependencies) یا نسخه‌های پکیج‌ها تأثیر می‌گذارد. (مثال: build: Update webpack configuration for faster builds)
• chore: برای تغییراتی که به فرآیند توسعه مربوط می‌شوند اما مستقیماً در کد منبع (Source Code) یا تست‌ها دیده نمی‌شوند؛ مانند به‌روزرسانی فایل‌های پیکربندی، ویرایش فایل .gitignore، یا وظایف نگهداری روتین. (مثال: chore: Update dependency versions in package.json)
• ci: تغییرات در فایل‌های پیکربندی CI/CD. (مثال: ci: Add Dockerfile for production deployment)

محدوده (Scope) - اختیاری

محدوده، بخشی از پروژه را که این تغییر بر آن تأثیر می‌گذارد، مشخص می‌کند. این بخش اختیاری است اما در پروژه‌های بزرگ بسیار مفید است. محدوده می‌تواند نام یک ماژول، کامپوننت، بخش خاصی از برنامه (مانند api، ui، auth) یا حتی نام یک فایل خاص باشد.

مثال: feat(auth): Implement two-factor authentication

در این مثال، auth محدوده است که نشان می‌دهد این قابلیت جدید مربوط به بخش احراز هویت است.

موضوع (Subject) - اجباری

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

قوانین کلیدی برای موضوع:

• حرف اول بزرگ: همیشه با یک حرف بزرگ شروع کنید. (مثال: Add نه add)
• افعال امری در انگلیسی (Imperative Mood): از افعال امری استفاده کنید، انگار که به سیستم دستور می‌دهید کاری را انجام دهد. این یک قرارداد رایج در بسیاری از پروژه‌های انگلیسی‌زبان است و باعث می‌شود پیام‌ها مختصر و مستقیم باشند. (مثال: Fix bug، Add feature، Update documentation به جای Fixes bug، Added feature، Updating documentation)
• کوتاه و گویا: موضوع باید تا حد امکان کوتاه باشد (توصیه می‌شود کمتر از 50 کاراکتر) و به‌طور خلاصه بگوید چه کاری انجام شده است.
• بدون نقطه‌گذاری در انتها: معمولاً نیازی به نقطه در انتهای موضوع نیست.

مثال کامل هدر: feat(api): Add endpoint for user profile retrieval

۲. بدنه (Body) - اختیاری

بدنه، جایی است که می‌توانید توضیحات مفصل‌تری در مورد تغییرات ارائه دهید. این بخش زمانی مفید است که:

• انگیزه تغییر: دلیل انجام این تغییر چیست؟ چه مشکلی را حل می‌کند؟ چه نیازی را برطرف می‌سازد؟
• توضیح "چرا" و "چه چیزی": بدنه باید توضیح دهد که چرا این تغییرات لازم بوده و چه چیزی را تغییر داده است، نه صرفاً "چگونه" این کار انجام شده است (چون کد خود گویای چگونگی است).
• پیامدهای تغییر: آیا این تغییر بر بخش‌های دیگر تأثیر می‌گذارد؟

قوانین کلیدی برای بدنه:

• جداکننده خط خالی: بدنه باید با یک خط خالی از هدر جدا شود.
• پیچیدن خطوط (Line Wrapping): هر خط در بدنه باید حداکثر 72 کاراکتر باشد تا در ابزارهای مختلف به‌خوبی نمایش داده شود.
• استفاده از پاراگراف: می‌توانید از پاراگراف‌های متعدد برای توضیح بهتر استفاده کنید.

مثال:

feat(api): Add endpoint for user profile retrieval

This commit introduces a new GET endpoint at /users/:id/profile
which allows clients to retrieve detailed information about a specific user.
This is necessary to support the new user profile page in the frontend application.
Previously, this information had to be fetched through multiple separate requests.

۳. فوتر (Footer) - اختیاری

فوتر برای ثبت اطلاعات فراداده‌ای (Metadata) مانند ارجاعات به مسائل، مسائل مسدود شده (Blocked Issues) یا تغییرات شکننده (Breaking Changes) استفاده می‌شود.

موارد رایج در فوتر:

• ارجاع به مسائل: با استفاده از کلیدواژه‌هایی مانند Closes، Fixes، Resolves و شماره Issue، می‌توانید کامیت را به یک Issue در GitHub، GitLab یا ابزارهای مشابه پیوند دهید.
• تغییرات شکننده (Breaking Changes): اگر کامیت شما باعث تغییرات ناسازگار با نسخه‌های قبلی می‌شود (Breaking Changes)، باید به صراحت در فوتر ذکر شود. این امر بسیار مهم است و معمولاً با کلیدواژه BREAKING CHANGE: مشخص می‌شود.

مثال:

feat(auth): Implement new JWT authentication flow

This commit introduces a completely new authentication flow using JWT
instead of session-based authentication. This change significantly improves
security and scalability.

Closes #123
Resolves #456
BREAKING CHANGE: The authentication mechanism has been updated from session-based
to JWT. Clients will need to adapt their authentication requests accordingly.
The old /login endpoint will be deprecated in the next release.

مثال‌های عملی از کامیت مسیج

بیایید چند مثال از کامیت مسیج‌های استاندارد را بر اساس سناریوهای مختلف ببینیم:

سناریوی ۱: اضافه کردن یک قابلیت جدید

کامیت مسیج:

feat(user-profile): Add avatar upload functionality

Users can now upload and change their profile avatar.
The image is automatically resized and stored in the cloud storage.
Supported formats: JPG, PNG, GIF. Max file size: 5MB.

Closes #789

سناریوی ۲: رفع یک باگ

کامیت مسیج:

fix(checkout): Prevent double submission of order

Fixed an issue where clicking the submit button multiple times
could lead to duplicate order entries. Implemented a debounce
mechanism on the button to prevent rapid clicks.

Fixes #101

سناریوی ۳: تغییرات در مستندات

کامیت مسیج:

docs: Update README with deployment instructions

Added a new section to the README file detailing the steps
required to deploy the application to a production server.
Includes environment variable setup and necessary commands.

سناریوی ۴: تغییرات شکننده (Breaking Change)

کامیت مسیج:

refactor(api): Remove legacy user endpoints

The old /api/v1/users endpoints have been removed and replaced
by the new /api/v2/users endpoints introduced in a previous commit.

BREAKING CHANGE: The endpoints /api/v1/users and /api/v1/users/:id
are no longer available. All clients must migrate to use the v2 endpoints.
This change was announced in release v2.0.0.

نکات طلایی و بهترین روش‌ها برای نوشتن کامیت مسیج

علاوه بر ساختار و انواع استاندارد، رعایت نکات زیر می‌تواند کیفیت کامیت مسیج‌های شما را به طرز چشمگیری افزایش دهد:

چگونه کامیت مسیج‌های خود را در گیت اعمال کنیم؟

پس از اعمال تغییرات خود در فایل‌ها، آن‌ها را به Staging Area اضافه کرده و سپس با دستور git commit کامیت می‌کنید. برای نوشتن پیام، می‌توانید از این روش‌ها استفاده کنید:

• روش پیش‌فرض (با ویرایشگر): اجرای دستور git commit بدون هیچ پارامتری، ویرایشگر پیش‌فرض شما را باز می‌کند و می‌توانید پیام کامل (هدر، بدنه، فوتر) را در آن وارد کنید.
• روش خط فرمان (با -m): برای پیام‌های کوتاه، می‌توانید از پارامتر -m استفاده کنید. این روش برای پیام‌های ساده یا زمانی که فقط هدر را وارد می‌کنید، مناسب است. (مثال: git commit -m "feat: Add basic user registration")
• ترکیب -m و -m: برای وارد کردن هدر و بدنه جداگانه از طریق خط فرمان. (مثال: git commit -m "fix: Resolve issue with empty cart" -m "This commit addresses the bug where the cart would incorrectly show as empty after adding items.")
• اصلاح آخرین کامیت (git commit --amend): اگر اشتباهی در آخرین کامیت خود مرتکب شده‌اید (مثلاً پیام اشتباه، فراموش کردن فایلی، یا نیاز به اصلاح پیام)، می‌توانید از این دستور استفاده کنید. این دستور آخرین کامیت را با تغییرات جدید بازنویسی می‌کند. (مثال: git commit --amend -m "feat: Implement user avatar upload")

سوالات متداول (FAQ)

چرا باید از افعال امری در انگلیسی برای کامیت مسیج استفاده کنم؟

استفاده از افعال امری (مانند Add, Fix, Change) یک قرارداد استاندارد در جامعه توسعه‌دهندگان گیت است. این روش باعث می‌شود پیام‌ها مختصر، مستقیم و واضح باشند. وقتی پیام را می‌خوانید، انگار که به سیستم دستور می‌دهید کاری را انجام دهد: "Add this feature"، "Fix that bug". این ساختار به طور مداوم در پروژه‌های بزرگ و متن‌باز مانند پروژه‌های GitHub استفاده می‌شود و به خوانایی و سرعت درک پیام کمک می‌کند.

آیا استفاده از Scope (محدوده) در کامیت مسیج اجباری است؟

خیر، استفاده از Scope کاملاً اختیاری است. اما در پروژه‌های بزرگ که بخش‌های مختلفی دارند (مانند ماژول‌های مختلف، یا کامپوننت‌های UI)، استفاده از Scope به دسته‌بندی و فهم بهتر تغییرات کمک شایانی می‌کند. به شما اجازه می‌دهد که به‌سرعت متوجه شوید که تغییر اعمال‌شده مربوط به کدام بخش از پروژه است، بدون نیاز به بررسی عمیق کد.

چگونه می‌توانم مطمئن شوم که تیم من از فرمت استاندارد کامیت مسیج پیروی می‌کند؟

یک راهکار مؤثر، استفاده از Git Hooks است. می‌توانید یک اسکریپت (مانند commit-msg) در پوشه .git/hooks مخزن خود قرار دهید که قبل از ثبت هر کامیت، فرمت پیام را بررسی کند و در صورت عدم رعایت استاندارد، جلوی ثبت کامیت را بگیرد. همچنین، برگزاری جلسات آموزشی و تکرار اهمیت این موضوع در تیم می‌تواند مؤثر باشد.

چه تفاوتی بین feat و refactor وجود دارد؟

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

آیا می‌توانم از کامیت مسیج‌های غیر استاندارد استفاده کنم؟

بله، از نظر فنی گیت به شما اجازه می‌دهد هر چیزی را به عنوان کامیت مسیج بنویسید. اما این کار توصیه نمی‌شود. استفاده از استانداردها، به‌ویژه Conventional Commits، مزایای زیادی برای همکاری تیمی، نگهداری پروژه و خودکارسازی فرآیندها دارد. اگر تیم شما فرمت خاصی را ترجیح می‌دهد، بهتر است روی آن استاندارد توافق کنید.

نتیجه‌گیری و گام‌های بعدی

نوشتن کامیت مسیج‌های استاندارد، یک مهارت کلیدی برای هر توسعه‌دهنده حرفه‌ای است. این کار نه تنها به سازماندهی و شفافیت پروژه کمک می‌کند، بلکه ارتباط مؤثر در تیم را تسهیل کرده و فرآیندهای توسعه و نگهداری را کارآمدتر می‌سازد. با پیروی از ساختار Conventional Commits، استفاده از افعال امری، و رعایت نکات طلایی که در این مقاله ذکر شد، می‌توانید تاریخچه گیت پروژه خود را به یک منبع ارزشمند و قابل اعتماد تبدیل کنید.

گام‌های عملی بعدی شما:

• شروع به تمرین: از همین امروز، سعی کنید برای هر کامیت جدید خود، یک پیام استاندارد بنویسید.
• توافق با تیم: اگر در یک تیم کار می‌کنید، این مقاله را با همکاران خود به اشتراک بگذارید و روی یک استاندارد مشترک توافق کنید.
• خودکارسازی: ابزارهای Git Hooks را بررسی کنید تا از رعایت استانداردها در تیم خود اطمینان حاصل کنید.
• مرور تاریخچه: تاریخچه گیت پروژه‌های قدیمی‌تر خود را مرور کنید و ببینید چگونه با رعایت این استانداردها می‌توانستید آن را بهبود بخشید.

به یاد داشته باشید، هر کامیت مسیج، داستانی از تغییرات پروژه شماست. آن را به بهترین شکل ممکن روایت کنید!

```