conventionalcommits.org/content/v1.0.0/index.ar.md

draft	aliases
false	/ar/

Conventional Commits 1.0.0

الملخص

مواصفة Conventional Commits هي اتفاقية خفيفة الوزن تتعلق برسائل الالتزام (commit messages).
توفر مجموعة سهلة من القواعد لإنشاء تاريخ التزام واضح؛ مما يسهل كتابة أدوات آلية تستند إليها.
تتوافق هذه الاتفاقية مع SemVer، بوصف الميزات، الإصلاحات، والتغييرات الجوهرية التي تتم في رسائل الالتزام.

يجب أن تكون رسالة الالتزام على النحو التالي:

---

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

---

تحتوي رسالة الالتزام على العناصر الهيكلية التالية، للتواصل مع مستخدمي مكتبتك:

1. fix: الالتزام من نوع fix يقوم بإصلاح خطأ في قاعدة الكود (يتوافق مع PATCH في الإصدار الدلالي).
2. feat: الالتزام من نوع feat يقدم ميزة جديدة إلى قاعدة الكود (يتوافق مع MINOR في الإصدار الدلالي).
3. BREAKING CHANGE: الالتزام الذي يحتوي على footer BREAKING CHANGE: أو إضافة ! بعد النوع/النطاق، يُدخل تغييراً كبيراً على API (يتوافق مع MAJOR في الإصدار الدلالي). يمكن أن يكون التغيير الجذري جزءًا من أي نوع من الالتزامات.
4. الأنواع الأخرى غير fix: و feat: مسموحة، مثل @commitlint/config-conventional (استنادًا إلى اتفاقية Angular) التي توصي بـ build:, chore:, ci:, docs:, style:, refactor:, perf:, test: وغيرها.
5. يُمكن إضافة footers أخرى غير BREAKING CHANGE: <description> والتي تتبع اتفاقية مشابهة لـ صيغة trail git.

الأنواع الإضافية ليست مفروضة من قبل مواصفة Conventional Commits، وليس لها تأثير ضمني في الإصدار الدلالي (إلا إذا تضمنت تغييرًا جذريًا).

يمكن توفير نطاق (scope) لنوع الالتزام، لتوفير معلومات سياقية إضافية ويكون محصورًا بين قوسين، مثل feat(parser): add ability to parse arrays.

أمثلة

رسالة التزام مع وصف و footer لتغيير جذري

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

رسالة التزام تحتوي على ! و footer لتغيير جذري

chore!: drop support for Node 6

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

رسالة التزام بدون body

docs: correct spelling of CHANGELOG

رسالة التزام تحتوي على نطاق

feat(lang): add Polish language

رسالة التزام تحتوي على body متعدد الفقرات و footers متعددة

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.

1. يجب أن تسبق الالتزامات بنوع، يتكون من اسم مثل feat، fix، وما إلى ذلك، متبوعًا بـ scope اختياري، و ! اختياري، والنقطتين الإلزاميتين والمسافة.
2. يجب استخدام النوع feat عندما يضيف الالتزام ميزة جديدة لتطبيقك أو مكتبتك.
3. يجب استخدام النوع fix عندما يمثل الالتزام إصلاحًا لخطأ في تطبيقك.
4. يمكن توفير scope بعد النوع. يجب أن يتكون scope من اسم يصف جزءًا من قاعدة الكود محاطًا بأقواس، مثل fix(parser):.
5. يجب أن يتبع الوصف مباشرة النقطتين والمسافة بعد النوع/النطاق. الوصف هو ملخص قصير للتغييرات في الكود، مثل fix: array parsing issue when multiple spaces were contained in string.
6. يمكن توفير body أطول بعد الوصف القصير، لتوفير معلومات سياقية إضافية حول تغييرات الكود. يجب أن يبدأ body بسطر فارغ بعد الوصف.
7. يمكن أن يتكون body من أي عدد من الفقرات مفصولة بأسطر جديدة.
8. يمكن توفير واحد أو أكثر من footers بعد سطر فارغ بعد body. يجب أن يتكون كل footer من رمز (token) متبوعًا إما بـ :<space> أو <space># متبوعًا بقيمة نصية (مستوحى من اتفاقية trailer الخاصة بـ git).
9. يجب أن يستخدم token الخاص بـ footer - بدلاً من أحرف المسافات، مثل Acked-by (يساعد هذا في التفريق بين قسم footers و body متعدد الفقرات). يتم استثناء BREAKING CHANGE، الذي يمكن أيضًا استخدامه كـ token.
10. قد تحتوي قيمة footer على مسافات وأسطر جديدة، ويجب أن يتوقف التحليل عندما يتم ملاحظة زوج جديد من token/الفاصل الصحيح.
11. يجب الإشارة إلى التغييرات الجذرية في بادئة النوع/النطاق للالتزام، أو كمدخل في footer.
12. إذا تم تضمينها كـ footer، يجب أن تتكون التغييرات الجذرية من النص بأحرف كبيرة BREAKING CHANGE، متبوعًا بنقطتين ومسافة ووصف، مثل BREAKING CHANGE: environment variables now take precedence over config files.
13. إذا تم تضمينها في بادئة النوع/النطاق، يجب الإشارة إلى التغييرات الجذرية بواسطة ! مباشرة قبل :. إذا تم استخدام !، يمكن حذف BREAKING CHANGE: من قسم footer، ويجب استخدام وصف الالتزام لوصف التغيير الجذري.
14. يمكن استخدام أنواع أخرى غير feat و fix في رسائل الالتزام، مثل docs: update ref docs.
15. لا يجب التعامل مع وحدات المعلومات التي تتكون منها Conventional Commits على أنها حساسة لحالة الأحرف من قبل المنفذين، باستثناء BREAKING CHANGE الذي يجب أن يكون بأحرف كبيرة.
16. يجب أن تكون BREAKING-CHANGE مرادفة لـ BREAKING CHANGE عند استخدامها كـ token في footer.

لماذا نستخدم Conventional Commits؟

• إنشاء CHANGELOGs تلقائيًا.
• تحديد رفع الإصدار الدلالي تلقائيًا (استنادًا إلى أنواع الالتزامات المضافة).
• التواصل بطبيعة التغييرات إلى الزملاء والجمهور وغيرهم من أصحاب المصلحة.
• تشغيل عمليات البناء والنشر.
• تسهيل مساهمة الأشخاص في مشاريعك من خلال السماح لهم باستكشاف تاريخ الالتزامات بشكل منظم.

الأسئلة المتكررة

كيف أتعامل مع رسائل الالتزام في مرحلة التطوير الأولية؟

نوصي بأن تتعامل كما لو أنك أصدرت المنتج بالفعل. عادةً ما يكون هناك شخص ما، حتى لو كانوا مطورين آخرين، يستخدمون البرنامج. سيرغبون في معرفة ما الذي تم إصلاحه وما هي التغييرات الكبيرة.

هل تكون الأنواع في عنوان الالتزام بأحرف كبيرة أو صغيرة؟

يمكن استخدام أي حالة، ولكن من الأفضل أن تكون متسقة.

ماذا أفعل إذا كان الالتزام يتوافق مع أكثر من نوع من الأنواع؟

يفضل أن تقوم بعمل عدة التزامات كلما كان ذلك ممكنًا. جزء من فائدة Conventional Commits هو دفعنا لإجراء التزامات وتنظيم أكثر.

ألا يشجع ذلك على الحد من سرعة التطوير والتكرار السريع؟

إنه يشجع على عدم التحرك بسرعة بطريقة غير منظمة. يساعدك على التحرك بسرعة على المدى الطويل عبر مشاريع متعددة مع مساهمين متنوعين.

هل قد تؤدي "Conventional Commits" إلى تقييد المطورين في نوع الـ commits التي يقومون بها لأنهم سيفكرون في الأنواع المقدمة؟

تشجع "Conventional Commits" المطورين على القيام بمزيد من أنواع الـ commits مثل الإصلاحات (fixes). بخلاف ذلك، فإن مرونة "Conventional Commits" تسمح لفريقك بتحديد أنواعهم الخاصة وتغيير تلك الأنواع مع مرور الوقت.

كيف يرتبط هذا بـ SemVer؟

يجب أن تترجم الـ commits من النوع fix إلى إصدارات PATCH. ويجب أن تترجم الـ commits من النوع feat إلى إصدارات MINOR. الـ commits التي تحتوي على BREAKING CHANGE، بغض النظر عن النوع، يجب أن تترجم إلى إصدارات MAJOR.

كيف يجب أن أقوم بتحديد الإصدارات لامتداداتي لمواصفة "Conventional Commits"، مثل @jameswomack/conventional-commit-spec؟

نوصي باستخدام SemVer لإصدار امتداداتك الخاصة لهذه المواصفة (ونشجعك على تطوير هذه الامتدادات!).

ماذا أفعل إذا استخدمت نوع commit خاطئ عن طريق الخطأ؟

عندما تستخدم نوعاً موجوداً في المواصفة ولكنه ليس النوع الصحيح، مثل fix بدلاً من feat

قبل الدمج أو إصدار الخطأ، نوصي باستخدام git rebase -i لتعديل تاريخ الـ commits. بعد الإصدار، تختلف عملية التصحيح اعتماداً على الأدوات والعمليات التي تستخدمها.

عندما تستخدم نوع commit غير موجود في المواصفة، مثل feet بدلاً من feat

في أسوأ الأحوال، إذا تم تمرير commit لا يتوافق مع مواصفة "Conventional Commits"، فليس هذا نهاية العالم. هذا يعني ببساطة أن هذا الـ commit لن يتم التعرف عليه بواسطة الأدوات التي تعتمد على هذه المواصفة.

هل يحتاج جميع المساهمين في مشروعي إلى استخدام مواصفة "Conventional Commits"؟

لا! إذا كنت تستخدم أسلوب "squash" في Git، يمكن للمسؤولين الرئيسيين تنظيف رسائل الـ commits عند الدمج، دون إضافة عبء على المساهمين العرضيين. إحدى الأساليب الشائعة لذلك هي أن يقوم نظام git تلقائيًا بـ "squash" الـ commits من طلب السحب (pull request) ويعرض نموذجًا للمسؤول الرئيسي لإدخال رسالة git commit المناسبة للدمج.

كيف تتعامل "Conventional Commits" مع الـ commits الخاصة بالتراجع (revert)؟

يمكن أن يكون التراجع عن الشيفرة معقداً: هل تقوم بالتراجع عن عدة commits؟ إذا كنت تتراجع عن ميزة (feature)، هل يجب أن يكون الإصدار التالي تصحيحاً (patch) بدلاً من ذلك؟

لا تبذل "Conventional Commits" جهداً صريحاً لتحديد سلوك التراجع. بدلاً من ذلك، نترك الأمر لمطوري الأدوات للاستفادة من مرونة الأنواع والتذييلات (types و footers) لتطوير منطقهم في التعامل مع التراجعات.

أحد التوصيات هو استخدام نوع revert، وتذييل يشير إلى SHAs الخاصة بالـ commits التي يتم التراجع عنها:

revert: لن نتحدث أبداً عن حادثة الـ noodle مرة أخرى

Refs: 676104e, a215868