16 KiB
| draft | aliases | |
|---|---|---|
| false |
|
رسائل الإيداع commits الاصطلاحية المتفق عليها في نظام التحكم في الإصدارات
يعرض هذا المقال مواصفات لجعل رسائل الإيداع commit messages مقروءة للبشر ولبرامج الأتمتة على حد سواء.
مقدمة
رسائل الإيداع الاصطلاحية هي مواصفات يسيرة تلتزم بها الرسائل كي تحقق شروطها، إذ توفر مجموعةً من القواعد لإنشاء سجل رسائل إيداع واضحة وصريحة، مما يجعلها أسهل لكي تستخدمها أدوات الأتمتة مباشرة.
هذا الاصطلاح متوافق مع الإدارة الدلالية لنُسخ البرمجيات SemVer، عن طريق وصف المميزات features، والإصلاحات fixes، والتغييرات الجذرية breaking changes في رسائل الإيداع.
يجب أن تكون هيكلية رسائل الإيداع كما يلي:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
تحتوي رسالة الإيداع العناصر التالية في هيكليتها، وذلك لإيصال المعنى بدقة مع مستخدم المكتبة سواء كان بشريًا أو أداة برمجية:
- إصلاح
:fixرسالة إيداع من نوعfixتصلح أو ترقع patch الخطأ في الشيفرة البرمجية، وهذا مرتبط بمصطلح الترقيعPATCHفي إدارة النسخ الدلالية Semantic Versioning. - ميزة
:featرسالة إيداع من نوعfeatتضيف ميزة جديدة للشيفرة البرمجية، وهذا مرتبط بمصطلح الترقيم البسيطMINORفي إدارة النسخ الدلالية. - تغيير جذري
:BREAKING CHANGEرسالة إيداع بتذييلBREAKING CHANGE:أو بإضافة!بعد كتابة النوعtypeأو النطاقscope، والتي تعرض تغييرًا جذريًا في الواجهة البرمجية. هذا مرتبط بمصطلح الترقيم الجذريMAJORفي إدارة النسخ الدلالية. يمكن أن تكونBREAKING CHANGEجزءًا من أي نوع في رسائل الإيداع. - تعد الأنواع المختلفة عن
:fixأو:featمسموح بها، مثلًا، commitlint/config-conventional@ بناءً على رسائل الإيداع الاصطلاحية في Angular التي تقترح هذه الأنواع: للبناء:buildوالعمل الروتيني:choreوالتكامل المستمر:ciوالتوثيقات:docsومتعلقات التصميم:styleوإعادة الهيكلية:refactorوالأداء:perfوالاختبار:testوغيرها. - قد تتبع التذييلات -بخلاف التغييرات الجذرية
<BREAKING CHANGE: <descriptionمواصفات شبيهة بتنسيقات git trailer format.
لا تعد بقية الأنواع متوافقة مع "رسائل الإيداع الاصطلاحية"، وليس لها أي تأثير ضمني في "إدارة النسخ الدلالية" إلا إذا احتوت على عبارة BREAKING CHANGE.
قد يُضاف النطاق scope، إلى نوع الإيداع لإضافة معلومات سياق contextual، وتُضّمن بين قوسين. مثلًا:
feat(parser): add ability to parse arrays
أمثلة
رسالة إيداع مع الوصف description وتغيير جذري مكتوب في التذييل
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.
رسالة إيداع دون متن body
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
المواصفات Specification
الكلمات الرئيسية مثل "يجب"، و"يجب ألا"، و"مطلوب"، و"يتوجب"، و"يتوجب ألا"، و"ينبغي"، و"لا ينبغي"، و"موصى به"، و"قد"، و"اختياري" في هذا المقال مفسّرة كما هو موضح في RFC 2119.
- يجب أن تُسبق رسائل الإيداع بالنوع، والذي يحتوي على اسم مثل: feat
أوfix، أو غيرها، متبوعة بالنطاق (اختياريًا)، أو علامة التعجب!اختياريًا. وبعدها النقطتين:` وبعدها مسافة. - يجب استخدام النوع
featعندما تُضاف ميزة جديدة للتطبيق أو المكتبة. - يجب استخدام النوع
fixعندما تُحل مشكلة في مشروعك. - قد يُضاف النطاق بعد النوع، ويجب أن يحتوي النطاق على اسم يصف جزءًا من الشيفرة البرمجية محاطة بقوسين، مثل
:fix(parse). - يجب أن يكون الوصف description مسبوقًا بالنطاق أو النوع التي تتبعهما النقطتان
:. الوصف هو خلاصة قصيرة للتغييرات في الشيفرة البرمجية، مثل:
array parsing issue when multiple spaces were contained in string
- قد يُضاف متن طويل لرسالة الإيداع بعد الوصف القصير، مضيفًا المزيد من المعلومات لهذا السياق المتعلق بتغييرات الشيفرة البرمجية، ويجب أن يبدأ المتن بسطر فارغ بعد الوصف.
- ليس لمتن رسالة الإيداع شكل معيّن مفروض، وقد تحتوي على فراغات من أسطر متعددة
- قد يحتوي تذييل واحد أو أكثر سطرًا فارغًا بعد المتن، ويجب على كل تذييل أن يحتوي رمزًا token متبوعًا إما بفراغ أو فراغ وعلامة "#"، ثم بعدها قيمة. وهذا مستلهم من git trailer convention.
- يجب أن يستخدم رمز التذييل
-بديلًا عن الفراغات بين الكلمات، مثل:Acked-by، وهذا يساعد في التفريق بين التذييل عن المتن ذي الأسطر المتعددة. الاستثناء الوحيد هو للتغييرات الجذريةBREAKING CHANGE، والتي قد تُستخدم رمزًا للتذييل. - قد يحتوي محتوى التذييل (وهو ما يأتي بعد الرمز) على فراغات وأسطر فارغة، ويجب أن ينتهي عند وجود الزوج الثاني الصالح من الرمز/الفاصل.
- يجب أن تُوضّح التغييرات الجذرية في بادئة النوع والنطاق لرسالة الإيداع، أو أن تحل محل الرمز في التذييل.
- إذا ذكرت التغييرات الجذرية في التذييل، يجب على التغيير الجذري أن يحتوي النص بالأحرف الكبيرة
BREAKING CHANGEمتبوعًا بالنقطتين:فالفراغ، والوصف. مثًلا:
BREAKING CHANGE: environment variables now take precedence over config files
- لو ضُمّنت التغييرات الجذرية في بداية النوع أو النطاق، فيجب توضيح وجود تغيرات جذرية عن طريق علامة التعجب
!مباشرةً بعد النقطتين:. لو استخدمت علامة التعجب، فيمكن مسحBREAKING CHANGE:من التذييل، ويتوجب أن يحتوي الوصف على وصف هذه التغييرات الجذرية. - قد تُستخدم الأنواع -بخلاف
featأوfix- في رسائل الإيداع، مثل:docs: update ref docs - يجب ألا يُتعامل مع وحدات المعلومات في رسائل الإيداع الاصطلاحية على أنها حساسة لحالة الأحرف case sensitive من قبل من يستخدم باستثناء التغيير الجذري الذي يجب أن يبقى بأحرفه الكبيرة.
- يجب أن يكون BREAKING-CHANGE مساويًا إلى BREAKING CHANGE، عند استخدامه رمزًا في التذييل.
لماذا يُعتمد نظام رسائل الإيداع الاصطلاحية؟
- إنشاء سجلات التغيير CHANGELOGs تلقائيًا.
- تحديد الإصدارات الدلالية لنُسخ البرمجيات semantic version bump تلقائيًا، استنادًا إلى أنواع رسائل الإيداع المكتوبة.
- إيصال طبيعة التغييرات إلى الزملاء في الفريق، والعامة، وكل من له علاقة بالمشروع.
- تفعيل عمليات البناء والنشر.
- تسهيل مشاركة الآخرين في مشاريعك، من خلال إعطائهم سجل تغييرات أكثر تنظيمًا.
الأسئلة الأكثر شيوعا
كيف يجب أن أتعامل مع رسائل الإيداع في مرحلة التطوير الأولية؟
نوصي بالمتابعة كما لو كنت قد أصدرت المنتج فعلًا، إذ يستخدم شخص ماعادةً برنامجك، ومن الممكن أن يكون أحد زملائك أثناء تطوير البرنامج، وسيرغبون في معرفة ما قد جرى إصلاحه وما الذي تعطل وما إلى ذلك.
هل الأنواع الموجودة في عنوان رسالة الإيداع ذات أحرف كبيرة أم صغيرة؟
يمكن استخدام أي منها ولكن من الأفضل أن يكون متسقًا.
ماذا أفعل إذا كانت رسالة الإيداعات تحتوي على تغييرات من أكثر من نوع؟
ارجع واكتب رسائل إيداع متعددة كلما أمكن ذلك؛ فجزءٌ من فائدة رسائل الإيداع الاصطلاحية هو قدرتها على دفعنا إلى كتابة رسائل إيداع وطلبات منظمة أكثر.
هل تثبط النقطة السابقة التطوير والانتقال السريع؟
لا تشجع على التحرك بسرعة غير منظمة، ولكنها تساعدك على التحرك بسرعة على المدى الطويل في مشاريع متعددة مع مساهمين متنوعين.
هل يمكن أن تؤدي رسائل الإيداع الاصطلاحية إلى دفع المطورين بتقييد نوع الإيداعات التي يعملونها لأنهم سيفكرون في الأنواع المقدمة؟
تشجعنا رسائل الإيداعات الاصطلاحية على المزيد من أنواع أخرى مثل الإصلاحات fixes. بخلاف ذلك، تسمح مرونة رسائل الإيداعات الاصطلاحية لفريقك بالتوصل إلى أنواع خاصة بهم وتغيير تلك الأنواع بمرور الوقت.
كيف يرتبط هذا بالإدارة الدلالية لنسخ البرمجيات SemVer؟
يجب ترجمة عمليات الإيداع إلى التالي من النسخ الدلالية SemVer:
- يُترجم النوع
fixإلى إصداراتPATCH. - يُترجم النوع
featإلى إصداراتMINOR.
يجب ترجمة BREAKING CHANGE إلى إصدارات MAJOR، بغض النظر عن نوع رسالة الإيداع.
كيف يمكنني إصدار الامتدادات وفقا لمواصفات رسائل الإيداعات الاصطلاحية، مثلا jameswomack/conventional-commit-spec@؟
نوصي باستخدام الإدارة الدلالية لنُسخ البرمجيات SemVer لإصدار الامتدادات لهذه المواصفات ونشجعك على إنشاء هذه الامتدادات.
ماذا أفعل إذا استخدمت نوع الإيداع الخاطئ دون قصد؟
عند استخدام نوع اصطلاحي ولكن ليس النوع الصحيح مثل fix بدلا من feat
قبل دمج الخطأ أو تحريره، نوصي باستخدام git rebase -i لتحرير سجل الإيداعات. ستكون عملية التنظيف بعد الإصدار مختلفة وفقًا للأدوات والعمليات التي تستخدمها.
عند استخدام نوع ليس من المواصفات مثل feet بدلا من feat
في أسوأ الأحوال، لن تكون نهاية العالم إذا كانت منطقة الالتزام لا تفي بمواصفات الإيداع التقليدية، فهذا يعني ببساطة أن الإيداع سيفوّت missed بالأدوات المستندة إلى المواصفات.
هل يحتاج جميع المساهمين إلى استخدام رسائل الإيداع الاصطلاحية؟
لا، إذا كنت تستخدم سير عمل قائم على squash على غيت Git، فيمكن للمشرفين الرئيسيين تنظيف رسائل الإيداع أثناء دمجها مما لا يضيف أي عبء عمل على مرسلي رسائل الإيداعات العاديين.
يتمثل سير العمل الشائع common workflow في جعل نظام غيت git يسحق squash رسائل الإيداع تلقائيًا من طلب سحب pull request ويقدم نموذجًا للمشرف الرئيسي لإدخال رسالة إيداع git المناسبة للدمج.
كيف تتعامل الإيداعات الاصطلاحية مع الإيداعات العكسية revert commits؟
يمكن أن يكون عكس الشيفرة البرمجية معقدًا. هل تعكس عن إيداعات متعددة؟ إذا عكست إحدى الميزات، فهل يجب أن يكون الإصدار التالي patch بدلًا من ذلك؟
لا تبذل رسائل الإيداع الاصطلاحية جهدًا واضحًا لتحديد سلوك عكس الإيداع revert behavior، بل تترك لأدوات المطورين لكي يستخدموا مرونة الأنواع والتذييلات لتطوير منطقهم في التعامل مع عمليات عكس الإيداعات.
إحدى التوصيات هي استخدام النوع revert، والتذييل الذي يشير إلى إيداعات ترميز SHA المعكوسة:
revert: let us never again speak of the noodle incident
Refs: 676104e, a215868