أعراف سجل التغييرات

أعراف سجل التغييرات

تحدّد هذه الصفحة العقد الذي يتّبعه كل مستودع عام من مستودعات ⁨NextPDF⁩ عند تسجيل تغيير ونشر إصدار. وهي مرجع للأعراف، ولا تحدّد سلوك الحزمة. توجد ملاحظات الإصدار لكل حزمة ولكل نسخة في ملف CHANGELOG.md الخاص بكل مستودع. تضمن هذه القواعد المشتركة أن يبقى ملخص سجل التغييرات عبر المستودعات متسقًا وخاليًا من التسريب.

⁨Conventional Commits 1.0.0⁩

يتبع عنوان كل إيداع الصيغة type(scope): description. ويكون type واحدًا مما يلي:

النوع	المعنى	يظهر للمستخدم	الأثر على الإصدار
feat	ميزة جديدة	نعم	زيادة طفيفة
fix	تصحيح سلوك	نعم	زيادة تصحيحية
perf	تحسين في الأداء دون تغيير في السلوك	نعم	زيادة تصحيحية
refactor	إعادة هيكلة داخلية دون أي تغيير ملحوظ	لا	لا شيء
docs	توثيق فقط	لا	لا شيء
test	اختبارات فقط	لا	لا شيء
build / ci	البناء أو خط المعالجة فقط	لا	لا شيء
chore	صيانة أو تبعيات أو أدوات	لا	لا شيء
revert	التراجع عن إيداع سابق	حسب الحالة	حسب الحالة

يُشار إلى التغيير الكاسر بعلامة ! بعد النوع أو النطاق (feat(api)!: …) أو بتذييل BREAKING CHANGE:. وترفع كلتا الصيغتين الإصدار الرئيسي بموجب ⁨Semantic Versioning.⁩ سجّل أي إصلاح متعلق بالأمن كي يتسنى ظهوره في عمود Security في الملخص عبر المستودعات.

⁨Semantic Versioning 2.0.0⁩

تُحسب زيادات الإصدار آليًا. أي إصدار يحتوي على أي تغيير كاسر يكون إصدارًا رئيسيًا. وإلا، فإن أي إصدار يحتوي على أي feat يكون إصدارًا طفيفًا. وإلا، فإن أي إصدار يحتوي على أي fix أو perf يكون إصدارًا تصحيحيًا. يجوز للحزم السابقة للإصدار 1.0 زيادة الإصدار الطفيف عند حدوث تغيير كاسر وفقًا لـ ⁨SemVer⁩ §4. ومع ذلك، يجب أن يظل الإيداع حاملًا لعلامة التغيير الكاسر كي يبقى الملخص دقيقًا.

التجميع وفق ⁨Keep a Changelog⁩

يتّبع ملف CHANGELOG.md الخاص بكل مستودع معيار ⁨Keep a Changelog 1.1.0⁩: تُجمَّع المُدخلات بحسب الإصدار المُطلَق ضمن Added وChanged وDeprecated وRemoved وFixed وSecurity. قد يحتوي قسم [Unreleased] على ملاحظات قيد التنفيذ داخل المستودع، لكن الملخص عبر المستودعات لا يحتسب إلا الإصدارات الموسومة والمُطلَقة. لا يظهر العمل غير المُطلَق أبدًا في الفهرس العام.

كيفية اشتقاق الملخص عبر المستودعات (وإبقائه خاليًا من التسريب)

يُنشأ جدول الملخص في فهرس سجل التغييرات بقراءة سجل ⁨Conventional Commits⁩ لكل مستودع، للقراءة فقط، عند أحدث وسم مُطلَق له، ثم عدّ الفئات. قواعد الاشتقاق محدودة عن قصد كي لا تتسرب أي تفاصيل داخلية:

1. أعداد، لا محتوى. لا يُعرَض إلا عدد الإيداعات لكل نوع يظهر للمستخدم. لا يُعرَض أي عنوان إيداع أو متنه أو تذييله أو تجزئته.
2. الأنواع التي تظهر للمستخدم فقط. تُستبعَد docs وtest وci وchore وrefactor لأنها لا تغيّر أي شيء يلاحظه مستهلك الحزمة.
3. المُطلَق فقط. لا يُحسَب أي إيداع إلا بعد أن يصبح جزءًا من إصدار موسوم لحزمة عامة.
4. لا معرّفات. لا تظهر أبدًا أي إشارات داخلية إلى مشكلة أو تذكرة أو دورة أو موجة أو عنصر عمل قد ترد في نطاق إيداع خاص، لأن نص النطاق نفسه لا يُعرَض أبدًا. لا يُقرَأ إلا النوع.
5. لا إسناد للأتمتة. لا تُقرَأ تذييلات أتمتة المساهمين ولا تُعرَض.

لهذا السبب، يكون سجل التغييرات العام ملخصًا حسب الفئات مع روابط إلى ملف CHANGELOG.md الخاص بكل حزمة، لا موجزًا مجمَّعًا للإيداعات. الملخص خالٍ من التسريب الداخلي بحكم تصميمه. ويبقى النص المرجعي للإصدار مع الحزمة المالكة له.

انظر أيضًا

• سجل التغييرات
• أعراف وصفات التكامل
• ⁨Conventional Commits 1.0.0⁩
• ⁨Semantic Versioning 2.0.0⁩