From 31634383f173b0aa74ed8bf6f95ae871c1fa3629 Mon Sep 17 00:00:00 2001 From: mostafa Date: Fri, 8 Nov 2024 13:29:55 +0330 Subject: [PATCH] feat(lang): add persian (farsi) translation --- config.yaml | 18 ++++ content/v1.0.0/index.fa.md | 192 +++++++++++++++++++++++++++++++++++++ 2 files changed, 210 insertions(+) create mode 100644 content/v1.0.0/index.fa.md diff --git a/config.yaml b/config.yaml index df9b06b..c3b9bc9 100644 --- a/config.yaml +++ b/config.yaml @@ -450,3 +450,21 @@ languages: list: - v1.0.0 rtl: true + + fa: + weight: 25 + languageName: "فارسی" + title: Conventional Commits + description: قراردادی برای افزودن معنای قابل خواندن توسط انسان و ماشین به پیام‌های کامیت + actions: + - label: خلاصه سریع + url: '#خلاصه' + - label: مشخصات کامل + url: '#مشخصات' + - label: مشارکت + url: 'https://github.com/conventional-commits/conventionalcommits.org' + versions: + current: v1.0.0 + list: + - v1.0.0 + rtl: true diff --git a/content/v1.0.0/index.fa.md b/content/v1.0.0/index.fa.md new file mode 100644 index 0000000..1497bbd --- /dev/null +++ b/content/v1.0.0/index.fa.md @@ -0,0 +1,192 @@ +--- +draft: false +aliases: ["/fa/"] +--- + +# Conventional Commits 1.0.0 + +## خلاصه + +Conventional Commits یک قرارداد سبک در بالای پیام‌های کامیت است. +این مجموعه قوانین آسانی را برای ایجاد یک تاریخچه کامیت واضح فراهم می‌کند +که امکان ساخت ابزارهای خودکار سازی در بالای آن را آسان‌تر می‌سازد. +این قرارداد با توصیف features (ویژگی‌ها)، fixes (اصلاحات) و breaking changes (تغییرات اساسی) انجام شده در پیام‌های کامیت، +خود را با [SemVer](http://semver.org) همسو می‌سازد. + +ساختار پیام commit باید به صورت زیر باشد: + +--- + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +--- + +
+کامیت دارای بخش‌های زیر است +تا هدف انجام کار را به مصرف کنندگان کتابخانه شما منتقل کند: + +1. **fix:** یک کامیت از _نوع_ `fix` باگی را در پایگاه کد شما برطرف می‌کند (این با [`PATCH`](http://semver.org/#summary) در Semantic Versioning مرتبط است). +1. **feat:** یک کامیت از _نوع_ `feat` یک ویژگی جدید به پایگاه کد اضافه می‌کند (این با [`MINOR`](http://semver.org/#summary) در Semantic Versioning مرتبط است). +1. **BREAKING CHANGE:** یک کامیت که دارای پاورقی `BREAKING CHANGE:‎` است، یا یک `!` را پس از نوع/تایپ اضافه می‌کند، یک تغییر API قطعی را معرفی می‌کند (با [`MAJOR`](http://semver.org/#summary) در Semantic Versioning مرتبط است). + یک BREAKING CHANGE می تواند بخشی از هر _نوع_ کامیتی باشد. +1. _تایپ‌های_ دیگر به غیر از `fix:‎` و `feat:‎` هم مجاز هستند، به عنوان مثال [‎@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (بر اساس قرارداد [Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) + تایپ‌های `build:‎` , `chore:‎` , `ci:‎` , `docs:‎` , `style:‎` , `refactor:‎` , `perf:‎` , `test:‎` و غیره را توصیه می‌کند. +1. _پاورقی‌های_ دیگر به غیر از `BREAKING CHANGE:‎ ‎` ممکن است ارائه شوند و از قراردادی مشابه با + [git trailer format](https://git-scm.com/docs/git-interpret-trailers) پیروی کند. + +تایپ اضافی توسط مشخصات Conventional Commits الزامی نیستند و تأثیر ضمنی در Semantic Versioning ندارند (مگر اینکه شامل یک BREAKING CHANGE باشند). +

+یک اسکوپ می‌تواند در کنار تایپ کامیت ارائه شود تا اطلاعات زمینه‌ای بیشتری را فراهم کند و در داخل پرانتز نوشته می‌شود، به عنوان مثال `feat(parser): add ability to parse arrays`. + +## مثال‌ها + +### پیام کامیت با توصیف و پاورقی تغییر اساسی + +``` +feat: allow provided config object to extend other configs + +BREAKING CHANGE: `extends` key in config file is now used for extending other config files +``` + +### پیام کامیت با `!` برای جلب توجه به تغییر اساسی + +``` +feat!: send an email to the customer when a product is shipped +``` + +### پیام کامیت با اسکوپ و `!` برای جلب توجه به تغییر اساسی + +``` +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 (می‌تواند)" و "OPTIONAL (اختیاری)" در این سند باید همانطور که در [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) توصیف شده است، تفسیر شوند. + +1. کامیت‌ها باید با یک تایپ که شامل یک اسم مانند `feat`، `fix` و غیره است، همراه با اسکوپ اختیاری، `!` اختیاری و دو نقطه و فاصله الزامی پیشوند شوند. +1. تایپ `feat` باید زمانی استفاده شود که یک کامیت ویژگی جدیدی به برنامه یا کتابخانه شما اضافه می‌کند. +1. تایپ `fix` باید زمانی استفاده شود که یک کامیت نشان‌دهنده رفع یک باگ در برنامه شماست. +1. یک اسکوپ می‌تواند بعد از تایپ ارائه شود. یک اسکوپ باید شامل یک اسم باشد که بخشی از پایگاه کد را توصیف می‌کند و در پرانتز قرار می‌گیرد، مثلاً `fix(parser):‎` +1. توضیحات باید بلافاصله بعد از پیشوند تایپ/اسکوپ و دونقطه و فاصله بیاید. + توضیحات خلاصه کوتاهی از تغییرات کد است، به عنوان مثال: _fix: array parsing issue when multiple spaces were contained in string_ +1. ممکن است پس از توضیحات کوتاه، یک بدنه طولانی‌تر ارائه شود که اطلاعات متنی اضافی در مورد تغییرات کد ارائه می‌کند. متن باید یک خط خالی بعد از توضیحات شروع شود. +1. بدنه کامیت آزاد است و می‌تواند شامل هر تعداد پاراگراف جدا شده با خط جدید باشد. +1. یک یا پاورقی می‌تواند بعد یک خط خالی پس از بدنه ارائه شود. هر پاورقی باید شامل یک توکن کلمه باشد، که به دنبال آن یا `‎:‎` یا `‎#‎` جداکننده و سپس یک مقدار رشته‌ای می‌آید (این از [git trailer format](https://git-scm.com/docs/git-interpret-trailers) الهام گرفته شده است). +1. توکن پاورقی باید از `-` به جای کاراکترهای فاصله استفاده کند، مثلاً `Acked-by` (این کمک می‌کند تا بخش پاورقی از بدنه چند پاراگرافی متمایز شود). یک استثنا برای `BREAKING CHANGE` وجود دارد که می‌تواند به عنوان یک توکن نیز استفاده شود. +1. مقدار یک پاورقی می‌تواند شامل فاصله‌ها و خطوط جدید باشد و تجزیه باید زمانی که جفت توکن/جداکننده پاورقی معتبر بعدی مشاهده شد، پایان یابد. +1. تغییرات اساسی باید در پیشوند تایپ/اسکوپ یک کامیت یا به عنوان یک ورودی در پاورقی نشان داده شوند. +1. اگر به عنوان یک پاورقی گنجانده شود، یک تغییر اساسی باید شامل متن بزرگ BREAKING CHANGE، به دنبال آن دو نقطه، فاصله و توصیف باشد، مثلاً + _BREAKING CHANGE: environment variables now take precedence over config files_. +1. اگر در پیشوند تایپ/اسکوپ گنجانده شود، تغییرات اساسی باید با یک `!` درست قبل از `:` نشان داده شوند. اگر از `!` استفاده شود، `‎BREAKING CHANGE:‎` می‌تواند از بخش پاورقی حذف شود و توصیف کامیت باید برای توصیف تغییر اساسی استفاده شود. +1. تایپ‌های دیگری به غیر از `feat` و `fix` می‌توانند در پیام‌های کامیت شما استفاده شوند، مثلاً _docs: update ref docs._ +1. واحدهای اطلاعاتی که Conventional Commits را تشکیل می‌دهند نباید توسط پیاده‌سازان به عنوان حساس به حروف کوچک و بزرگ در نظر گرفته شوند، به استثنای BREAKING CHANGE که باید با حروف بزرگ باشد. +1. BREAKING-CHANGE باید هنگامی که به عنوان یک توکن در یک پاورقی استفاده می‌شود، مترادف با BREAKING CHANGE باشد. + +## چرا از Conventional Commits استفاده کنیم + +- تولید خودکار CHANGELOG‌ها. +- تعیین خودکار افزایش نسخه معنایی (بر اساس تایپ‌های کامیت‌های ثبت شده). +- انتقال ماهیت تغییرات به اعضای تیم، عموم و سایر ذینفعان. +- راه‌اندازی فرآیندهای ساخت و انتشار. +- آسان‌تر کردن مشارکت افراد در پروژه‌های شما، با اجازه دادن به آنها برای کاوش در تاریخچه کامیت ساختاریافته‌تر. + +## سوالات متداول + +### چگونه باید با پیام‌های کامیت در فاز توسعه اولیه برخورد کنم؟ + +ما توصیه می‌کنیم که طوری پیش بروید که انگار محصول را قبلاً منتشر کرده‌اید. معمولاً کسی (حتی اگر همکاران توسعه‌دهنده نرم‌افزارتان باشند) از نرم‌افزار شما استفاده می‌کند. آنها می‌خواهند بدانند چه چیزی اصلاح شده، چه چیزی خراب شده و غیره. + +### آیا تایپ‌ها در عنوان کامیت با حروف بزرگ هستند یا کوچک؟ + +هر نوع حروف می‌تواند استفاده شود، اما بهتر است که ثبات داشته باشید. + +### اگر کامیت با بیش از یکی از تایپ‌های کامیت مطابقت داشته باشد چه کار کنم؟ + +هر زمان که ممکن است، برگردید و چندین کامیت ایجاد کنید. بخشی از مزیت Conventional Commits توانایی آن در هدایت ما به سمت ایجاد کامیت‌ها و PR‌های سازمان‌یافته‌تر است. + +### آیا این مانع از توسعه سریع و تکرار سریع نمی شود؟ + +از توسعه سریع به روشی بی نظم جلوگیری می کند. این به شما کمک می کند تا بتوانید در پروژه های متعدد با مشارکت کنندگان مختلف به سرعت در درازمدت حرکت کنید. + +### آیا ممکن است Conventional Commits توسعه‌دهندگان را به محدود کردن نوع کامیت‌هایی که انجام می‌دهند وادار کند زیرا آنها به تایپ‌های ارائه شده فکر خواهند کرد؟ + +Conventional Commits ما را تشویق می‌کند تا تایپ‌های خاصی از کامیت‌ها مانند اصلاحات (fix) را بیشتر انجام دهیم. علاوه بر این، انعطاف‌پذیری Conventional Commits به تیم شما اجازه می‌دهد تا تایپ‌های خود را ایجاد کنند و این تایپ‌های را در طول زمان تغییر دهند. + +### این چه ارتباطی با SemVer دارد؟ + +کامیت‌های تایپ `fix` باید به انتشارهای `PATCH` ترجمه شوند. کامیت‌های تایپ `feat` باید به انتشارهای `MINOR` ترجمه شوند. کامیت‌ها با `BREAKING CHANGE` در کامیت‌ها، صرف نظر از نوع، باید به انتشارهای `MAJOR` ترجمه شوند. + +### چگونه باید افزونه‌های خود را برای مشخصات Conventional Commits نسخه‌بندی کنم، مثلاً `‎@jameswomack/conventional-commit-spec`؟ + +ما توصیه می‌کنیم از SemVer برای انتشار افزونه‌های خود به این مشخصات استفاده کنید (و شما را تشویق می‌کنیم که این افزونه‌ها را ایجاد کنید!) + +### اگر به طور تصادفی از تایپ کامیت اشتباه استفاده کردم چه کار کنم؟ + +#### وقتی از تایپی استفاده کردید که در مشخصات هست اما تایپ درستی نیست، مثلاً `fix` به جای `feat` + +قبل از ادغام یا انتشار اشتباه، ما توصیه می‌کنیم از `git rebase -i` برای ویرایش تاریخچه کامیت استفاده کنید. پس از انتشار، پاکسازی بسته به ابزارها و فرآیندهایی که استفاده می‌کنید متفاوت خواهد بود. + +#### وقتی از تایپی استفاده کردید که در مشخصات _نیست_ ، مثلاً `feet` به جای `feat` + +در بدترین سناریو، پایان دنیا نیست اگر کامیتی ثبت شود که با مشخصات Conventional Commits مطابقت ندارد. به این معنی است که آن کامیت توسط ابزارهایی که بر اساس مشخصات هستند نادیده گرفته خواهد شد. + +### آیا همه مشارکت‌کنندگان من باید از مشخصات Conventional Commits استفاده کنند؟ + +نه! اگر از یک گردش کار مبتنی بر squash در Git استفاده می‌کنید، نگهدارندگان اصلی می‌توانند پیام‌های کامیت را بدون اضافه کردن بار کاری به مشارکت‌کنندگان غیر جدی هنگام ادغام تمیز کنند. +یک گردش کار رایج برای این کار این است که سیستم git شما به طور خودکار کامیت‌ها را از یک pull request می‌گیرد و فرمی را برای نگهدارنده اصلی ارائه دهد تا پیام کامیت git مناسب را وارد کند. + +### Conventional Commits چگونه با کامیت‌های برگشت(revert) برخورد می‌کند؟ + +برگرداندن کد می‌تواند پیچیده باشد: آیا چندین کامیت را برمی‌گردانید؟ اگر یک ویژگی را برگردانید، آیا انتشار بعدی باید یک patch باشد؟ + +Conventional Commits تلاش صریحی برای تعریف رفتار برگشت نمی‌کند. در عوض، ما آن را به نویسندگان ابزار واگذار می‌کنیم تا از انعطاف‌پذیری _انواع_ و _پاورقی‌ها_ برای توسعه منطق خود برای مدیریت برگشت‌ها استفاده کنند. + +یک توصیه استفاده از نوع `revert` و یک پاورقی است که به SHAهای کامیت که برگردانده می‌شوند اشاره می‌کند: + +``` +revert: let us never again speak of the noodle incident + +Refs: 676104e, a215868 +```