Conventional Commits 1.0.0

خلاصه

مشخصات Commits Conventional یک قرارداد سبک وزن در بالای پیام های commit است. این مجموعه قوانین آسانی را برای ایجاد یک تاریخچه ارتکاب صریح فراهم می کند. که نوشتن ابزارهای خودکار در بالای آن را آسان تر می کند. این کنوانسیون با [SemVer] (http://semver.org) مطابقت دارد، با تشریح ویژگی‌ها، اصلاحات، و شکستن تغییرات ایجاد شده در پیام‌های commit.

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

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

کامیت استاندارد شامل المان های ساختاری زیر است تا کاربرات ارتباط بهتری با کتابخانه شما برقرار کنند:

1. fix: کامیت نوع fix نشانگر اصلاح یک باگ در کد شماست(مصداق PATCH در ورژن‌بندی سمانتیک)
2. feat: کامیت نوع feat ایجاد یک ویژگی جدید را در کد معرفی میکند(مصداق MINOR در ورژن‌بندی سمانتیک)
3. BREAKING CHANGE: یک کامیت که شامل فوتر با عنوان BREAKING CHANGE: باشد یا ! در کنار نوع/اسکوپ آن آمده باشد معرف یک تغییر ناسازگار (Breaking Change) در API است. (مصداق MAJOR در ورژن‌بندی سمانتیک) BREAKING CHANGE می‌تواند بخشی از هر نوع کامیت باشد.
4. انواع دیگری بغیر از fix: و feat نیز مجاز هستند. بعنوان مثال @commitlint/config-conventional (بر پایه Angular convention) build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, و غیره را پیشنهاد می‌دهد.
5. فوتر های دیگری نیز بجز BREAKING CHANGE: <description> ممکن است اراوه شوند و از قاعده git trailer format پیروی کنند.

نواع (Types) اضافی دیگر در مشخصات Conventional Commits اجباری نیستند و به‌طور پیش‌فرض تأثیری در نسخه‌بندی معنایی (Semantic Versioning) ندارند (مگر اینکه شامل یک BREAKING CHANGE باشند). همچنین می‌توان برای نوع (Type) یک کامیت، یک اسکوپ (Scope) تعریف کرد تا اطلاعات بیشتری در مورد زمینه تغییرات ارائه دهد. اسکوپ داخل پرانتز قرار می‌گیرد؛ به‌عنوان مثال: feat(parser): add ability to parse arrays

مثال

کامیت همراه با توضیح و فوتر Breaking Change

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

کامیت همراه ! بمنظور جلب توجه برای BREAKING CHANGE

feat!: send an email to the customer when a product is shipped

کامیت همراه اسکوپ و ! بمنظور جلب توجه برای BREAKING CHANGE

feat(api)!: send an email to the customer when a product is shipped

کامیت همراه ! و فوتر BREAKING CHANGE بطور همزمان

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

کامیت بدون توضیح

docs: correct spelling of CHANGELOG

کامیت همراه اسکوپ

feat(lang): add Polish language

کامیت همراه چندین خط توضیح و چندین خط فوتر

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

مشحصات

کلمات کلیدی “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” باید طبق RFC 2119 تفسیر شوند.

1. کامیت‌ها باید(MUST) با یک نوع مانند feat, fix و غیره شروع شوند و اسکوپ و ! بصورت اختیاری(OPTIONAL) در ادامه آورده شود که دونقطه و فاصله ضروری(REQUIRED) است.
2. نوع feat باید(MUST) وقتی استفاده شود که کامیت یک ویژگی جدید به برنامه یا کتابخانه شما اضافه کند.
3. نوع fix باید(MUST) وقتی استفاده شود که کامیت یک باگ از برنامه یا کتابخانه شما برطرف کند.
4. ممکن(MAY) است بعد از نوع اسکوپ بیان شود. یک اسکوب باید(MUST) یک اسم داخل پرانتز باشد که اسکوپ کامیت را توضیح دهد، بعنوان مثال fix(parser):
5. توضیح باید(MUST) بلافاصله بعد از دونقطه و فاصله پس از نوع/اسک.پ آورده شود. این توضیح شامل یک متن کوتاه درباره تغییر درحال کامیت است، مثلا fix: array parsing issue when multiple spaces were contained in string.
6. ممکن(MAY) است پس از توضیحات کوتاه، توضیح طولانی‌تری ارائه شود که اطلاعات متنی بیشتری در مورد تغییرات کد ارائه می‌کند. متن باید یک خط خالی بعد از توضیحات اول شروع شود.
7. بصورت آزاد است و ممکن(MAY) است از هر تعداد پاراگراف جدا شده از خط جدید تشکیل شده باشد.
8. ممکن(MAY) است یک یا چند فوتر بعد از یک خط خالی بعد از بدنه توضیحات ارائه شود. هر فوتر باید(MUST) شامل یک توکن (کلمه کلیدی) باشد که به دنبال آن یک جداکننده : (دو نقطه و یک فاصله) یا # (یک فاصله و علامت #) قرار می‌گیرد و سپس یک مقدار متنی (String Value) (این قالب‌بندی از کنوانسیون تریلرهای گیت git trailer convention الهام گرفته شده است).
9. نشانه فوتر باید(MUST) از «-» به جای کاراکترهای فضای خالی استفاده کند، به عنوان مثال، «Acked-by» (این به تمایز بخش t,jv از بدنه کمک می کند). یک استثنا برای BREAKING CHANGE ایجاد شده است که ممکن است به عنوان نشانه نیز استفاده شود.
10. مقدار فوتر ممکن(MAY) است حاوی فاصله و خطوط جدید باشد و پارسر باید(MUST) با مشاهده جفت نشانه/جداکننده فوتر معتبر بعدی خاتمه یابد.
11. BREAKING CHANGE باید(MUST) در پیشوند نوع/حوزه یک کامیت یا به عنوان ابتدای فوتر حضور داشته باشد.
12. اگر BREAKING CHANGE در فوتر گنجانده شود، آن(MUST) حروف بزرگ BREAKING CHANGE، به دنبال آن دو نقطه، فاصله و توضیحات باشد، به عنوان مثال، مثلا BREAKING CHANGE: environment variables now take precedence over config files.
13. اگر BREAKING CHANGE در ابتدای کامیت گنجانده شود، باید(MUST) با یک ! بلافاصله قبل از : نشان داده شود. اگر از ! استفاده شود، BREAKING CHANGE ممکن(MAY) است از قسمت فوتر حذف شود، در این حال خوب است(SHALL) توضیح کامیت باید برای توصیف BREAKING CHANGE استفاده شود.
14. انواعی غیر از feat و fix ممکن(MAY) است در پیام‌های کامیت شما استفاده شود، به عنوان مثال docs: update ref docs.
15. عبارات کلیدی استاندارد کامیت نباید(MUST NOT) بعوان حساس به حروف کوچک و بزرگ شناخته شوند به استثنا BREAKING CHANGE که حروف بزرگ است.
16. BREAKING-CHANGE باید(MUST) مترادف با BREAKING CHANGE باشد، زمانی که به عنوان توکن در فوتر استفاده می شود.

چرا از استاندارد کامیت استفاده می‌کنیم؟

• ایجاد خودکار CHANGELOG.
• تعیین خودکار ورژن‌بندی سمانتیک(بر اساس نوع کامیت).
• انتقال مفهوم تغییرات به هم تیمی ها، مردم و سایر ذینفعان.
• راه اندازی فرآیندهای ساخت و انتشار.
• ساده‌تر کردن فرآیند مشارکت بقیه افراد در پروژه با ایجاد یک تاریخچه ساختارمند از کامیت ها.

سوالات پرتکرار

چگونه در فاز راه‌اندازی اولیه با پیان کامیت برخورد کنم؟

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

آیا نوع‌ها باید از حروف کوچک استفاده کنند یا حروف بزرگ؟

تفاوتی نم‌کند اما بهتر است یکدست باشد.

اگر گامیت با بیش از یک نوع از انواع استاندارد مطابقت داشت، چه کاری باید بکنم؟

ترجیحا به عقب برگردید و کامیت های بیشتری تولید کنید. بخشی از مزایای قاعده استاندارد توانایی آن در سوق دادن ما به انجام تعهدات و روابط عمومی بیشتر است.

آیا این موضوع باعث کاهش سرعت توسعه نمی‌شود؟

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

آیا قاعده استاندارد کامیت ممکن است باعث شود توسعه‌دهندگان نوع کامیت‌های خود را محدود کنند، زیرا آن‌ها به انواع تعیین‌شده فکر می‌کنند؟

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

این موضوع چگونه به SemVer مرتبط می‌شود؟

کامیت‌های از نوع fix باید به انتشارهای PATCH تبدیل شوند. کامیت‌های از نوع feat باید به انتشارهای MINOR تبدیل شوند. کامیت‌هایی که شامل BREAKING CHANGE باشند، بدون توجه به نوع آن‌ها، باید به انتشارهای MAJOR تبدیل شوند.

چگونه باید نسخه‌گذاری افزونه‌های خود به مشخصات قاعده استاندارد کامیت را انجام دهم، مثلاً @jameswomack/conventional-commit-spec؟

ما توصیه می‌کنیم از SemVer برای انتشار افزونه‌های خود به این مشخصات استفاده کنید (و شما را تشویق می‌کنیم که این افزونه‌ها را ایجاد کنید!).

اگر به اشتباه از نوع کامیت اشتباه استفاده کردم، چه کار باید بکنم؟

اگر از نوعی استفاده کرده‌اید که در مشخصات وجود دارد اما نوع صحیح نیست، مثلاً fix به جای feat

قبل از ادغام یا انتشار اشتباه، توصیه می‌کنیم از git rebase -i برای ویرایش تاریخچه کامیت‌ها استفاده کنید. پس از انتشار، پاک‌سازی بستگی به ابزارها و فرآیندهایی دارد که استفاده می‌کنید.

اگر از نوعی استفاده کرده‌اید که در مشخصات وجود ندارد، مثلاً feet به جای feat

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

آیا همه مشارکت ککندگان پروژه من باید از مشخصات قاعده استاندارد کامیت پیروی کنند؟

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

قاعده استاندارد کامیت چگونه کامیت‌های بازگشتی (Revert) را مدیریت می‌کند؟

بازگرداندن کد (Revert) می‌تواند پیچیده باشد: آیا چندین کامیت را بازمی‌گردانید؟ اگر یک قابلیت را بازگردانید، آیا نسخه بعدی باید یک وصله (Patch) باشد؟

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

یک توصیه این است که از نوع revert و یک فوتر که به SHAهای کامیت‌های بازگردانی‌شده ارجاع می‌دهد، استفاده کنید:

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868