> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# الإصدارات SemVer مع سجل التغييرات Changelog
- URL: https://arabroot.io/articles/الاصدارات-semver-مع-سجل-التغييرات-changelog/
- Published: 2026-11-03T09:13:55.000Z
- Updated: 2026-11-03T10:13:15.000Z
- Description: كيف تعطي كل إصدار رقماً يعرف منه من يستخدم الكود هل الانتقال آمن، وتولد سجل التغييرات من رسائل Commits دون أن يضيع تغيير مهم.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, DevOps والتشغيل, DevOps وCI/CD, Docker والحاويات, الاستضافة الذاتية

إذا عملت على مشروع يستخدمه أحد غيرك فقد مر بك هذا الموقف بشكل أو بآخر: يتصل بك مطور تطبيق الجوال ويقول إن شاشة الطلبات أصبحت تعرض خمسين طلباً بدل عشرين منذ يوم الأحد، ويسألك ماذا تغير، فتفتح سجل Git فتجد عشرات ال Commits منذ آخر نشر، منها «update stuff» و«fix» و«wip»، ولا تعرف أيها وصل إلى الإنتاج ومتى. أو يأتيك فريق العمليات ويسأل: هل نستطيع أن ننشر هذا الإصدار الجديد دون أن يتعطل الشريك الذي يستخدم ال API؟ وأنت لا تملك إجابة إلا «أعتقد ذلك». أو تشغل `npm install` صباح الأحد على كود لم يلمسه أحد منذ الخميس، فيفشل البناء لأن مكتبة صغيرة في أعماق الاعتمادات Dependencies أصدرت نسخة جديدة.

وكل هذه المواقف لها سبب واحد: لا يوجد اتفاق واضح على ما يعنيه «الإصدار»، أي ما هو الشيء الذي أطلقناه، وما اسمه، وما الذي تغير فيه، وهل يستطيع من يستخدمه أن ينتقل إليه بأمان. وفي هذا المقال سوف نتابع فريق المتجر الإلكتروني نفسه الذي بنينا معه [الإعداد ومتغيرات البيئة](https://arabroot.io/articles/%D9%85%D8%AA%D8%BA%D9%8A%D8%B1%D8%A7%D8%AA-%D8%A7%D9%84%D8%A8%D9%8A%D8%A6%D8%A9-environment-variables-%D8%AA%D8%B7%D8%A8%D9%8A%D9%82-%D9%88%D8%A7%D8%AD%D8%AF-%D9%84%D9%83%D9%84-%D8%A7%D9%84%D8%A8%D9%8A%D8%A6%D8%A7%D8%AA/)، ولديه هذه المرة خدمة اسمها `shop-api` يستخدمها تطبيق الجوال وشريك خارجي، ونبني معه طريقة إطلاق Release كاملة: رقم إصدار له معنى بحسب SemVer، ورسائل Commits تقرؤها الأدوات، وسجل تغييرات Changelog يقرؤه الإنسان، و Tag في Git لا يتحرك، و Image في Docker بوسوم مفهومة. وكل خطوة سوف نجربها في مختبر حقيقي مع الأداة git-cliff، ومعها مشكلتان حقيقيتان واجهتانا أثناء التجربة.

وسوف نناقش في هذا المقال ما يلي:

- لماذا تحتاج أرقام إصدارات أصلاً، ومن أين جاء SemVer، وما الذي يعد به كل رقم فيه.
- التغيير غير المتوافق Breaking Change، ولماذا هو أصعب مما يبدو، وما حدث مع المكتبة is-promise في 2020.
- البدائل مثل CalVer، ورسائل Conventional Commits، وسجل التغييرات بصيغة Keep a Changelog.
- مختبر يطلق الإصدار 1.4.0 ثم 2.0.0 من مستودع حقيقي، مع Commit بلا نوع اختفى من السجل، و Image رسمية تقطع المعاملات التي فيها مسافات.
- النطاقات Version Ranges في npm، وترتيب الإصدارات، ووسوم Docker، وما يحدث إذا نقلت Tag بعد نشره.
- خطوات الإطلاق في CI، وإصدار ال API نفسه، والأخطاء الشائعة، وقائمة تحقق.

## لماذا تحتاج أرقام إصدارات؟ Why Versioning

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

وبدون أرقام يستخدم الفريق بدائل سيئة: التاريخ «نسخة يوم الأحد»، أو بصمة ال Commit التي لا يتذكرها أحد، أو الأسوأ من ذلك «آخر نسخة» التي تعني شيئاً مختلفاً لكل شخص. وقد رأينا في [مقال البيئات](https://arabroot.io/articles/%D8%A7%D9%84%D8%A8%D9%8A%D8%A6%D8%A7%D8%AA-%D9%88%D9%85%D8%B9%D8%A7%D9%8A%D9%86%D8%A9-%D8%A7%D9%84%D9%85%D9%8A%D8%B2%D8%A7%D8%AA-%D9%88-gitops-%D9%84%D9%84%D9%81%D8%B1%D9%82/) أن ال Image تبنى مرة واحدة وتنقل بين البيئات، وهذا النقل يحتاج اسماً ثابتاً لكل Image، فإذا قلت «انقل 1.4.0 إلى الإنتاج» فالجميع يعرف عن ماذا تتكلم، وإذا رجعت إلى 1.3.0 فالجميع يعرف أين رجعت.

ولكن الرقم وحده لا يكفي إذا لم يكن له معنى متفق عليه. فالفريق في القصة كان يرفع الرقم الأخير مع كل نشر، فوصل إلى 1.0.47، ولم يكن الرقم يقول شيئاً عن طبيعة التغيير، فالنسخة 1.0.31 التي غيرت شكل الأسعار في ال API وأوقفت تطبيق الشريك كانت تبدو مثل 1.0.30 التي أصلحت خطأً إملائياً. وهنا تأتي فكرة الإصدار الدلالي Semantic Versioning: أن يكون لكل جزء من الرقم معنى، فيعرف القارئ من الرقم وحده هل الانتقال آمن.

## من أين جاء SemVer؟ History

قبل SemVer كانت لكل مشروع طريقته، فبعض المشاريع ترفع الرقم الرئيسي لأسباب تسويقية، وبعضها يستخدم الأرقام الزوجية للإصدارات المستقرة والفردية للتطويرية كما كانت نواة Linux تفعل في التسعينيات، وبعضها لا يغير الرقم الرئيسي أبداً مهما تغير. وكانت النتيجة ما سماه كاتب المواصفة لاحقاً جحيم الاعتمادات Dependency Hell: كلما زاد عدد المكتبات التي يعتمد عليها مشروعك أصبح التحديث أصعب، فإما أن تقفل كل مكتبة على نسخة واحدة فلا تحصل على أي إصلاح، أو تسمح بالتحديث فتفاجأ بتغيير غير متوافق.

وفي سنة 2010 تقريباً كتب Tom Preston-Werner، أحد مؤسسي GitHub، مواصفة قصيرة سماها [Semantic Versioning](https://semver.org/?ref=arabroot.io)، ولم يخترع فيها شيئاً جديداً، وإنما كتب بشكل رسمي ما كانت مشاريع كثيرة تفعله أصلاً، وجعله قواعد مرقمة يمكن أن تبنى عليها الأدوات. ثم صدرت النسخة 2.0.0 من المواصفة، وهي النسخة المستخدمة حتى اليوم، وأصبح npm وCargo وComposer وGo Modules وأغلب مديري الحزم يعتمدون عليها أو على شيء قريب منها في حساب النطاقات والترقيات. والنقطة المهمة في المواصفة أنها تبدأ بشرط: يجب أن يكون لديك واجهة عامة Public API معلنة، لأن الأرقام كلها تقاس بالنسبة لها.

## قواعد SemVer الأساسية Specification

رقم الإصدار في SemVer ثلاثة أرقام `MAJOR.MINOR.PATCH`، وكل رقم وعد لمن يستخدم الكود وليس عداداً للعمل. والصورة التالية تبين الأجزاء الخمسة مع أمثلة من خدمة `shop-api` التي سوف نطلقها في المختبر:

![الرقم 2.0.0-rc.1+build.7 بالألوان، وتحته خمسة صناديق: MAJOR الرئيسي لتغيير يجبر المستخدم على تعديل كوده مثل 1.4.0 إلى 2.0.0 عندما أصبحت المبالغ هللات بدل ريالات، وMINOR الثانوي لميزة جديدة متوافقة مثل 1.3.0 إلى 1.4.0 مع حفظ السلة، وPATCH للإصلاح دون تغيير الواجهة مثل 1.4.0 إلى 1.4.1، وPre-release أقل من الإصدار نفسه 2.0.0-rc.1 أقل من 2.0.0، وBuild Metadata لا تدخل في المقارنة، وتحتها أن الإصدار 0.y.z للتطوير الأولي](https://arabroot.io/content/images/2026/11/semver-releases-01-anatomy.webp)

أجزاء رقم الإصدار، وما يعد به كل جزء

والقواعد باختصار كما تنص عليها المواصفة: ارفع رقم الإصلاح PATCH عندما تصلح أخطاء بطريقة متوافقة مع ما قبلها، وارفع الرقم الثانوي MINOR عندما تضيف وظيفة جديدة متوافقة مع ما قبلها، وعندها يرجع رقم الإصلاح إلى صفر، وارفع الرقم الرئيسي MAJOR عندما تغير الواجهة العامة بطريقة غير متوافقة، وعندها يرجع الرقمان الآخران إلى صفر. أي أن الانتقال من 1.4.0 إلى 1.4.1 أو إلى 1.5.0 يجب أن يكون آمناً دون أي تعديل عند المستخدم، أما الانتقال إلى 2.0.0 فيحتاج أن يقرأ ما تغير ويعدل كوده.

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

### ما هي الواجهة العامة Public API؟

كل قواعد SemVer تقاس بالنسبة للواجهة العامة، ولذلك أول سؤال يجب أن يجيب عنه الفريق هو: ما الذي نعد به من يستخدمنا؟ وفي مكتبة برمجية الإجابة واضحة نسبياً: الدوال والكلاسات المعلنة ومعاملاتها وما ترجعه. أما في خدمة مثل `shop-api` فالواجهة العامة أوسع مما يتوقع الفريق عادة، فهي تشمل المسارات Endpoints، وأسماء الحقول في JSON وأنواعها، ورموز الحالة HTTP Status Codes، ورسائل الأخطاء إذا كان العملاء يعتمدون عليها، والقيم الافتراضية مثل حجم الصفحة، وحتى ترتيب العناصر إذا لم تقل في التوثيق إنه غير مضمون. وكلما كان التوثيق أوضح فيما هو مضمون وما هو غير مضمون كان قرار رقم الإصدار أسهل.

وفي حالة تطبيق ويب يستخدمه الناس من المتصفح فقط، مثل موقع المتجر نفسه، فالواجهة العامة للمستخدم النهائي ليست شيئاً يعتمد عليه كود آخر، ولذلك تستخدم فرق كثيرة لهذه التطبيقات أرقاماً أبسط أو تواريخ كما سيأتي، وتحتفظ بـ SemVer للمكتبات وال APIs التي يستخدمها كود آخر.

### الإصدار 0.y.z للتطوير الأولي Initial Development

تنص المواصفة على أن الرقم الرئيسي صفر للتطوير الأولي، وأن أي شيء قد يتغير فيه في أي وقت، والواجهة العامة لا تعتبر مستقرة. وتقول كذلك إن الإصدار 1.0.0 هو الذي يعلن الواجهة العامة، وإذا كان الكود يستخدم في الإنتاج فغالباً يجب أن يكون 1.0.0 أصلاً. ومشكلة هذه القاعدة أن كثيراً من المشاريع تبقى سنوات على 0.x لتتجنب الالتزام، بينما يعتمد عليها آلاف المستخدمين في الإنتاج. ولذلك اتفقت الأدوات مثل npm وCargo على معاملة الرقم الثاني في 0.x كأنه الرقم الرئيسي، أي أن 0.3.0 إلى 0.4.0 تعتبر تغييراً غير متوافق، وسوف نرى أثر ذلك على النطاقات في المختبر.

### النسخ التجريبية Pre-release مع Build Metadata

يمكن أن تضيف بعد الرقم شرطة ومعرفات مثل `2.0.0-rc.1` أو `2.0.0-beta.2`، وهذه نسخة قبل الإصدار Pre-release، وقيمتها في الترتيب أقل من الإصدار نفسه، فـ `2.0.0-rc.1` تأتي قبل `2.0.0`. والمعرفات تقارن جزءاً جزءاً، والأجزاء الرقمية تقارن كأرقام، ولذلك `rc.9` قبل `rc.10`، وهذا ما لا تفعله أغلب أدوات ترتيب النصوص كما سنرى. ويمكن كذلك أن تضيف بعد علامة `+` بيانات البناء Build Metadata مثل `+build.7` أو بصمة ال Commit، وهذه لا تدخل في المقارنة أبداً، فالإصداران `1.4.0+build.7` و`1.4.0+build.9` متساويان في نظر أي أداة تتبع المواصفة.

وفائدة النسخ التجريبية في قصة الفريق كانت واضحة عندما جاء وقت الإصدار 2.0.0، فقد أطلق الفريق `2.0.0-rc.1` للشريك ليجرب عليه، والنطاقات في مديري الحزم لا تختار النسخ التجريبية إلا إذا طلبتها صراحة، فلم يصل المرشح إلى أي مستخدم آخر بالخطأ.

## التغيير غير المتوافق Breaking Change أصعب مما يبدو

قد يبدو تحديد التغيير غير المتوافق سهلاً: حذفت مساراً، أو غيرت اسم حقل، أو غيرت نوعه. وهذه حالات واضحة فعلاً، مثل ما سيفعله الفريق في المختبر عندما يجعل المبالغ في `GET /orders` أرقاماً صحيحة بالهللات بدل أرقام عشرية بالريالات، فكل عميل يعرض المبلغ كما هو سوف يعرض 1250 بدل 12.5\. ولكن هناك حالات أقل وضوحاً، فتغيير حجم الصفحة الافتراضي من 20 إلى 50 لا يحذف شيئاً ولا يغير أي نوع، ومع ذلك تطبيق الجوال الذي افترض أن الصفحة 20 عنصراً، فصمم الشاشة عليها، تأثر به.

وهذه الظاهرة لها اسم معروف بين المهندسين هو قانون Hyrum Hyrum's Law، نسبة إلى المهندس Hyrum Wright في Google، ونصه تقريباً: مع عدد كاف من مستخدمي أي API، لا يهم ما وعدت به في العقد، فكل سلوك يمكن ملاحظته في نظامك سوف يعتمد عليه أحد ما. أي أن الواجهة العامة الحقيقية ليست ما كتبته في التوثيق، وإنما كل ما يستطيع المستخدم أن يراه. ولذلك لا يوجد تغيير متوافق بنسبة 100%، والهدف الواقعي أن تكون الواجهة الموثقة واضحة، وأن تعامل أي تغيير في سلوك ملحوظ بحذر، وأن تكتبه في سجل التغييرات حتى لو قررت أنه لا يستحق رقماً رئيسياً جديداً.

### قصة من الواقع: is-promise 2.2.0 في أبريل 2020 Case Study

في 25 أبريل 2020 نشر مشرفو مكتبة is-promise، وهي مكتبة من سطر واحد تقريباً تتحقق هل القيمة Promise، الإصدار 2.2.0، وهو بحسب SemVer إصدار ثانوي يجب أن يكون آمناً. وكان التغيير إضافة دعم ES Modules مع الحقل `"type": "module"` في ملف `package.json`، وهذا جعل Node.js يعامل ملف المكتبة كوحدة ES، فأصبح كل كود يستدعيها بالطريقة القديمة `require()` يفشل بالخطأ `ERR_REQUIRE_ESM`. وبما أن المكتبة كانت تستخدم بشكل غير مباشر في أدوات منتشرة جداً، فقد ظهر الخطأ خلال ساعة في create-react-app وفي إطار Serverless وفي خطوط CI كثيرة، كما يظهر في [البلاغ على مستودع المكتبة](https://github.com/then/is-promise/issues/13?ref=arabroot.io) الذي امتلأ بالتعليقات في ذلك اليوم. ولم يغير أحد من هؤلاء المستخدمين سطراً في كوده، وإنما كانت النطاقات مثل `^2.1.0` تقبل 2.2.0 تلقائياً.

والدرس من هذه القصة ليس أن SemVer لا يعمل، وإنما أن رقم الإصدار وعد يكتبه إنسان، والإنسان يخطئ في تقدير ما هو متوافق، خصوصاً في التغييرات التي تبدو داخلية مثل طريقة التحميل. ولذلك تحتاج الحماية من جهتين: من جهة من يطلق، فيختبر الإصدار مع طرق الاستخدام الحقيقية قبل أن يقرر رقمه، ومن جهة من يستخدم، فيقفل الإصدارات في ملف القفل Lockfile ولا يحدث إلا بقرار واختبار، كما سيأتي في قسم النطاقات. وتقول المواصفة نفسها في أسئلتها الشائعة إنك إذا أطلقت تغييراً غير متوافق برقم ثانوي بالخطأ فعليك أن تصلحه بإصدار جديد يعيد التوافق، وتوثق ذلك، ولا تعدل الإصدار المنشور.

## هل SemVer مناسب لكل شيء؟ البديل CalVer

ليس كل مشروع يحتاج SemVer. فالتطبيقات التي يستخدمها الناس مباشرة ولا يعتمد عليها كود آخر، والمنتجات التي تطلق بجدول زمني ثابت، تستخدم غالباً الإصدار بالتاريخ Calendar Versioning واختصاراً [CalVer](https://calver.org/?ref=arabroot.io). ومن أشهر الأمثلة Ubuntu، فالإصدار 24.04 صدر في أبريل 2024، والرقم وحده يقول لك عمر النسخة، و[دورة إصدارات Ubuntu](https://ubuntu.com/about/release-cycle?ref=arabroot.io) مبنية على هذا الجدول. ومشاريع كثيرة تجمع بين الاثنين، مثل Node.js الذي يستخدم SemVer للأرقام ولكنه يطلق إصداراً رئيسياً جديداً بجدول ثابت مرتين في السنة، كما في [صفحة إصداراته](https://nodejs.org/en/about/previous-releases?ref=arabroot.io).

والقرار بين الاثنين يعتمد على سؤال واحد: من يقرأ الرقم وماذا يريد أن يعرف منه؟ فإذا كان القارئ كوداً يحتاج أن يقرر هل التحديث آمن فالأنسب SemVer. وإذا كان القارئ إنساناً يريد أن يعرف عمر النسخة وهل ما زالت مدعومة فالأنسب CalVer. وفي قصة الفريق اختار الفريق SemVer لخدمة `shop-api` لأن تطبيق الجوال والشريك يعتمدان عليها، واختار رقماً بسيطاً بالتاريخ لموقع المتجر الذي لا يعتمد عليه أحد.

## رسائل Conventional Commits: النوع قبل الوصف

إذا كان رقم الإصدار يعتمد على نوع التغييرات، فمن يعرف نوع كل تغيير؟ الحل البسيط أن يقرر الشخص الذي يطلق الإصدار بعد أن يقرأ كل ال Commits، وهذا يعمل مع عشرة Commits ويفشل مع مئة. والحل الأفضل أن يكتب كل مطور نوع التغيير في رسالة ال Commit نفسها لحظة كتابته، لأنه أكثر من يعرفه، وهذا ما تفعله مواصفة [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/?ref=arabroot.io). والصيغة كما يلي:

```text
<type>(<optional scope>)<optional !>: <description>

[optional body]

[optional footer(s)], for example: BREAKING CHANGE: <what breaks and what to do>
```

والأنواع الأساسية في المواصفة اثنان: `feat` لميزة جديدة، ويقابلها رفع الرقم الثانوي، و`fix` لإصلاح، ويقابلها رفع رقم الإصلاح. وعلامة `!` بعد النوع، أو سطر `BREAKING CHANGE:` في آخر الرسالة، تعني تغييراً غير متوافق، ويقابلها رفع الرقم الرئيسي. وتسمح المواصفة بأنواع أخرى مثل `docs` و`refactor` و`perf` و`test` و`ci` و`chore`، وهذه لا تغير الرقم وحدها. والنطاق Scope بين القوسين اختياري ويقول أي جزء من الكود تغير، مثل `fix(checkout)`.

وفائدة هذه الصيغة أنها تحول السؤال الصعب «ما رقم الإصدار التالي؟» إلى حساب بسيط تقوم به أداة: انظر إلى كل ال Commits منذ آخر Tag، فإذا وجدت علامة تغيير غير متوافق فالرقم الرئيسي، وإلا فإذا وجدت `feat` فالثانوي، وإلا فرقم الإصلاح. ولكن لاحظ أن الأداة لا تعرف إلا ما كتبه المطور، فإذا كتب `fix` على تغيير غير متوافق فسوف تطلق الأداة رقم إصلاح بكل ثقة، والمراجعة في طلب الدمج Pull Request هي المكان الذي يجب أن يسأل فيه أحد: هل هذا التغيير متوافق فعلاً؟

## سجل التغييرات Changelog لمن يقرأ

سجل التغييرات ملف في المستودع، اسمه عادة `CHANGELOG.md`، فيه ما تغير في كل إصدار بلغة يفهمها من يستخدم الكود. ويضع موقع [Keep a Changelog](https://keepachangelog.com/en/1.1.0/?ref=arabroot.io) مبادئ بسيطة له: السجل للبشر وليس للآلات، ولكل إصدار قسم بتاريخه، والتغييرات تجمع في أنواع ثابتة هي Added للإضافات، وChanged للتغييرات في سلوك موجود، وDeprecated لما سيحذف لاحقاً، وRemoved لما حذف، وFixed للإصلاحات، وSecurity للثغرات، وفي أعلى السجل قسم Unreleased لما دخل ولم يطلق بعد. وأشهر جملة في الموقع أنه لا يجوز أن تلصق سجل Git في سجل التغييرات، والسبب أن سجل Git مليء بال Commits التي لا تهم المستخدم، مثل تعديل الاختبارات وإصلاح خطأ إملائي في تعليق، ورسائله مكتوبة للمطورين.

وقد يتساءل البعض: إذا كانت الأداة تولد السجل من ال Commits، أليس هذا لصقاً لسجل Git؟ والإجابة أنه ليس كذلك بشرطين: أن تختار الأداة ال Commits التي تهم المستخدم فقط، فتتجاهل `docs` و`test` و`ci`، وأن يراجع إنسان السجل قبل الإطلاق ويعدل ما يحتاج تعديلاً. أي أن الأداة تكتب المسودة والإنسان يقرر، وهذا ما سوف نفعله في المختبر.

## المختبر Lab: إطلاق shop-api مع git-cliff

الأداة التي سوف نستخدمها هي [git-cliff](https://git-cliff.org/docs/?ref=arabroot.io)، وهي أداة مفتوحة المصدر مكتوبة بلغة Rust، تقرأ سجل Git وتولد سجل التغييرات بقالب تتحكم فيه، وتحسب رقم الإصدار التالي من أنواع ال Commits. واخترناها لأنها ملف تنفيذي واحد لا يحتاج Node.js ولا Python، وتعمل من Docker Image رسمية، فلا تفرض لغة معينة على المشروع. واستخدمنا الإصدار [2.14.2](https://github.com/orhun/git-cliff/releases/tag/v2.14.2?ref=arabroot.io) مع Git 2.48.1.

### المستودع Repository: من v1.3.0 إلى اليوم

بدأنا بمستودع فيه الإصدار السابق 1.3.0 مع Tag مشروح Annotated، ثم خمسة Commits حقيقية كل منها يغير ملفاً، كما يحدث في أسبوعين من العمل:

```bash
git init -b main shop-api && cd shop-api
printf '{\n  "name": "shop-api",\n  "version": "1.3.0"\n}\n' > package.json
printf 'ORDERS_PAGE_SIZE = 20\nVAT_DECIMALS = 4\nTOKEN_TTL_HOURS = 23\n' > settings.py
git add -A && git commit -m "chore(release): 1.3.0"
git tag -a v1.3.0 -m "shop-api 1.3.0"

echo 'def save_cart(user): ...' > cart.py
git add -A && git commit -m "feat(cart): save the cart for logged-in users"
sed -i 's/VAT_DECIMALS = 4/VAT_DECIMALS = 2/' settings.py
git commit -am "fix(checkout): round VAT to 2 decimals before sending to the gateway"
echo 'GET /orders?page=2' >> README.md
git commit -am "docs: add API examples for /orders"
sed -i 's/ORDERS_PAGE_SIZE = 20/ORDERS_PAGE_SIZE = 50/' settings.py
git commit -am "update stuff"
sed -i 's/TOKEN_TTL_HOURS = 23/TOKEN_TTL_HOURS = 24/' settings.py
git commit -am "fix(auth): refresh token expired one hour early"
git log --oneline --decorate
```

```text
0dd9b7a (HEAD -> main) fix(auth): refresh token expired one hour early
a8bf900 update stuff
8a4ce8c docs: add API examples for /orders
7435e25 fix(checkout): round VAT to 2 decimals before sending to the gateway
489d1ab feat(cart): save the cart for logged-in users
c685708 (tag: v1.3.0) chore(release): 1.3.0
```

ولاحظ ال Commit الرابع: رسالته «update stuff» ولا نوع لها، ولكنه غير حجم الصفحة الافتراضي في `GET /orders` من 20 إلى 50، وهو بالضبط التغيير الذي اشتكى منه مطور تطبيق الجوال في بداية المقال. وهذا ليس مثالاً مصطنعاً، فأغلب المستودعات فيها Commits بهذا الشكل، والسؤال هو ماذا تفعل بها الأداة.

وملف إعداد الأداة `cliff.toml` في جذر المستودع، كتبناه ليخرج السجل بأقسام Keep a Changelog:

```ini
# git-cliff configuration: Keep a Changelog sections from Conventional Commits
[changelog]
header = "# Changelog\n\nAll notable changes to shop-api. Format: Keep a Changelog, versions: SemVer.\n\n"
body = """
{% if version %}## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}{% else %}## [Unreleased]{% endif %}
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | striptags | trim }}
{% for commit in commits %}
- {% if commit.breaking %}**BREAKING** {% endif %}{% if commit.scope %}{{ commit.scope }}: {% endif %}{{ commit.message | upper_first }}\
{% endfor %}
{% endfor %}\n
"""
trim = true

[git]
conventional_commits = true
filter_unconventional = true
require_conventional = true
commit_parsers = [
  { message = "^feat", group = "<!-- 0 -->Added" },
  { message = "^fix", group = "<!-- 1 -->Fixed" },
  { message = "^(perf|change|refactor)", group = "<!-- 2 -->Changed" },
  { message = "^revert", group = "<!-- 3 -->Removed" },
  { message = '^chore\(release\)', skip = true },
  { message = "^(docs|test|ci|chore|style|build)", skip = true },
]
protect_breaking_commits = true
tag_pattern = "v[0-9].*"
sort_commits = "oldest"
```

في الإعداد أعلاه لاحظ التالي:

- `commit_parsers` يحول نوع كل Commit إلى قسم في السجل، والتعليق `<!-- 0 -->` قبل اسم القسم حيلة لترتيب الأقسام، والقالب يحذفه عند الطباعة بالفلتر `striptags`.
- الأنواع `docs` و`test` و`ci` و`chore` لا تظهر في السجل، لأنها لا تهم من يستخدم ال API.
- `protect_breaking_commits` يمنع إخفاء أي Commit غير متوافق حتى لو كان نوعه من الأنواع المتجاهلة، فالمستخدم يجب أن يعرف عنه دائماً.
- `require_conventional = true` يجعل الأداة تفشل إذا وجدت Commit بلا نوع، وسوف نرى بعد قليل لماذا أضفناه.
- `tag_pattern` يحدد أي وسوم Tags تعتبر إصدارات، حتى لا تعتبر الأداة وسماً مثل `deploy-2026-09` إصداراً.

### مشكلة واجهتنا: Image الأداة تقطع المعاملات Arguments عند المسافة

أول تجربة كانت حساب الرقم التالي بالأمر `--bumped-version`، ونجحت. ثم أردنا أن نضيف إلى السجل سطراً يدوياً بالخيار `--with-commit`، كما سيأتي، فكتبنا الأمر بالشكل الطبيعي:

```bash
docker run --rm -v "$PWD:/app" -w /app orhunp/git-cliff:2.14.2 \
  --unreleased --bump --with-commit "fix(orders): default page size of GET /orders is now 50, was 20"
```

```text
error: unexpected argument 'page' found

Usage: git-cliff [FLAGS] [OPTIONS] [--] [RANGE]
```

الأداة تقول إنها استلمت كلمة `page` كمعامل مستقل، أي أن النص الذي بين علامتي الاقتباس انقطع عند المسافات. وجربنا الصيغة `--with-commit=...` فكانت النتيجة نفسها، فالمشكلة ليست في طريقة كتابتنا. ففتحنا ال Image لنرى كيف تشغل الأداة:

```bash
docker inspect orhunp/git-cliff:2.14.2 --format '{{json .Config.Entrypoint}}'
docker run --rm --entrypoint cat orhunp/git-cliff:2.14.2 /usr/local/bin/entrypoint.sh
```

```text
["sh","/usr/local/bin/entrypoint.sh"]
#!/bin/sh
if [ "$(id -u)" -ne "$(stat -c '%u' .)" ]; then
  eids="$(stat -c '--euid %u --egid %g' .)"
fi
exec ${eids:+setpriv --clear-groups $eids} git-cliff $@
```

والسبب في السطر الأخير: `$@` بدون علامتي اقتباس، والطرفية تقسم كل معامل فيه مسافات إلى كلمات قبل أن تمرره إلى الأداة، والصحيح `"$@"`. والسكربت موجود ليشغل الأداة بنفس مستخدم مالك المجلد، حتى لا يكتب ملفات بمالك root في مستودعك. والحل أن تتجاوز السكربت وتشغل الأداة مباشرة بالخيار `--entrypoint`، مع الانتباه لملكية الملفات التي تكتبها إذا كنت على Linux، ولذلك عرفنا اختصاراً نستخدمه في بقية المختبر:

```bash
C(){ docker run --rm -e NO_COLOR=1 -v "$PWD:/app" -w /app --entrypoint git-cliff orhunp/git-cliff:2.14.2 "$@"; }
```

والدرس العام من هذه المشكلة أن Image الأداة جزء من خط الإطلاق مثل الأداة نفسها، فإذا وضعتها في خط CI فاختبرها بالمعاملات الحقيقية التي سوف تستخدمها، بما فيها النصوص التي فيها مسافات، قبل أن تعتمد عليها في يوم الإطلاق.

### مشكلة ثانية: ال Commit بلا نوع اختفى من السجل Unconventional Commit

قبل أن نضيف `require_conventional` إلى الإعداد كانت الأداة تعمل بإعدادها الافتراضي، فحسبت الرقم وولدت السجل كما يلي:

```text
WARN  git_cliff_core::changelog > process_commits: 1 commit(s) were skipped due to parse error(s) (run with `-vv` for details)
## [1.4.0] - 2026-11-03

### Added

- cart: Save the cart for logged-in users

### Fixed

- checkout: Round VAT to 2 decimals before sending to the gateway
- auth: Refresh token expired one hour early
```

الرقم 1.4.0 صحيح، لأن هناك `feat` واحداً، والسجل نظيف، ولكن تغيير حجم الصفحة غير موجود فيه أصلاً. والسبب أن الأداة لا تعرف نوع «update stuff»، فتجاهلته وطبعت تحذيراً واحداً في أعلى المخرج، يمر عليه أي شخص دون أن ينتبه، والتفصيل لا يظهر إلا مع `-vv`. أي أن أهم تغيير في هذا الإصدار بالنسبة لتطبيق الجوال هو الوحيد الذي لن يقرأ عنه أحد. وهذه هي المشكلة الحقيقية في أي سجل مولد آلياً: الأداة لا تكذب، ولكنها تسكت.

ولذلك أضفنا `require_conventional = true`، فأصبحت الأداة ترفض أن تعمل:

```bash
C --bumped-version
```

```text
ERROR git_cliff_core::process > process_commits: Commit a8bf900 is not conventional:
    | update stuff
Error: UnconventionalCommitsError(1)
```

وهذا هو السلوك الصحيح لخط الإطلاق، فالفشل يجبر إنساناً أن ينظر إلى ال Commit ويقرر. ولكن ال Commit دخل الفرع الرئيسي وربما وصل إلى نسخ الآخرين، فلا نريد أن نعيد كتابة التاريخ بالأمر `rebase`. والحل الذي توفره الأداة في [توثيق تجاوز ال Commits](https://git-cliff.org/docs/usage/skipping-commits?ref=arabroot.io) هو ملف `.cliffignore` فيه بصمات ال Commits التي تتجاهلها الأداة، ثم نضيف وصف التغيير يدوياً بالخيار `--with-commit`، فيصبح للتغيير سطر في السجل بالنوع الصحيح:

```bash
printf '# "update stuff": changed the default page size, described by hand in 1.4.0 (--with-commit)\n%s\n' \
  $(git rev-parse a8bf900) > .cliffignore
git add .cliffignore && git commit -m "ci: ignore unconventional commit a8bf900 in the changelog"
C --bumped-version
```

```text
v1.4.0
```

واخترنا للتغيير النوع `change` الذي أضفناه إلى قسم Changed في الإعداد، لأن تغيير حجم الصفحة ليس إصلاحاً ولا ميزة، وإنما تغيير في سلوك موجود. وناقش الفريق هل يستحق رقماً رئيسياً، وقرر أنه لا يستحق لأن التوثيق يقول إن العميل يجب أن يتبع روابط الصفحات وألا يفترض حجماً ثابتاً، ولكن يجب أن يظهر في السجل بوضوح، وأن يبلغ به مطور تطبيق الجوال قبل النشر. وهذا مثال حي على ما قلناه في قسم قانون Hyrum: القرار في الرقم، والصدق في السجل.

والحماية الحقيقية من تكرار هذه المشكلة ليست `.cliffignore`، وإنما فحص في خط CI على كل طلب دمج يرفض أي Commit بلا نوع قبل أن يدخل الفرع الرئيسي، مثل خطوة في [Gitea Actions](https://arabroot.io/articles/gitea-actions-%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-ci-cd-%D8%B9%D9%84%D9%89-%D8%AE%D8%A7%D8%AF%D9%85%D9%83/) تشغل الأمر `C --unreleased` بنفس الإعداد، فإذا فشل فشل طلب الدمج.

### الإطلاق Release: السجل ثم ال Commit ثم ال Tag

الآن نطلق الإصدار بأربع خطوات: نحسب الرقم، ونكتب السجل في الملف مع السطر اليدوي، ونحدث الرقم في `package.json`، ثم Commit و Tag مشروح:

```bash
V=$(C --bumped-version 2>/dev/null)
C --bump --with-commit "change(orders): GET /orders returns 50 items per page by default, was 20" -o CHANGELOG.md
sed -i "s/\"version\": \"1.3.0\"/\"version\": \"${V#v}\"/" package.json
git add -A && git commit -m "chore(release): ${V#v}"
git tag -a "$V" -m "shop-api ${V#v}"
cat CHANGELOG.md
```

```text
# Changelog

All notable changes to shop-api. Format: Keep a Changelog, versions: SemVer.

## [1.4.0] - 2026-11-03

### Added

- cart: Save the cart for logged-in users

### Fixed

- checkout: Round VAT to 2 decimals before sending to the gateway
- auth: Refresh token expired one hour early

### Changed

- orders: GET /orders returns 50 items per page by default, was 20

## [1.3.0] - 2026-09-01
```

في المخرج أعلاه لاحظ التالي:

- ال Commit من نوع `docs` لا يظهر، وال Commits من نوع `ci` التي أضفنا بها الإعداد وملف التجاهل لا تظهر كذلك، فالسجل فيه ما يهم من يستخدم ال API فقط.
- قسم 1.3.0 فارغ لأن ال Commit الوحيد فيه من نوع `chore(release)` المتجاهل، وفي مشروع حقيقي تبدأ باستخدام الأداة من إصدار معين وتترك السجل القديم كما كتب يدوياً.
- تاريخ الإصدار هو تاريخ ال Commit الذي يحمل ال Tag، وليس تاريخ أول تغيير فيه.

وال Tag الذي أنشأناه من النوع المشروح Annotated بالخيار `-a`، وهو كائن مستقل في Git له كاتب وتاريخ ورسالة، بخلاف ال Tag الخفيف Lightweight الذي هو مجرد اسم يشير إلى Commit. وتوصي [صفحة الأمر git tag](https://git-scm.com/docs/git-tag?ref=arabroot.io) باستخدام المشروح للإصدارات والخفيف للاستخدام المؤقت الخاص، ومن أسباب ذلك أن أوامر مثل `git describe` تتجاهل الوسوم الخفيفة افتراضياً. والمثال التالي يبين محتوى ال Tag وما يقوله `git describe` بعد Commitين جديدين:

```bash
git cat-file -p v1.4.0 | head -6
git describe --tags
git describe --tags --dirty     # after editing a file without committing
```

```text
object 421beba3c017f898bd0f750fefb8e4bb35a8bf58
type commit
tag v1.4.0
tagger Shop Dev <dev@example.com> 1793700080 +0300

shop-api 1.4.0
v1.4.0-2-ge977e02
v1.4.0-2-ge977e02-dirty
```

والسطر `v1.4.0-2-ge977e02` مفيد جداً لأي بناء ليس إصداراً، فهو يقول: آخر إصدار 1.4.0، وبعده Commitان، وال Commit الحالي `e977e02`، و`-dirty` تعني أن هناك تعديلات لم تحفظ. ولذلك تضعه فرق كثيرة في بيانات البناء Build Metadata لكل Image تبنى من الفرع الرئيسي، فتعرف من أي كود جاءت أي نسخة تجريبية.

### الإصدار الرئيسي التالي Major Release: 2.0.0

بعد الإطلاق أضاف الفريق إصلاحاً واحداً، فسألنا الأداة عن الرقم التالي، ثم أضاف التغيير الذي غير المبالغ إلى هللات، مع علامة `!` وسطر `BREAKING CHANGE` يشرح ما على العميل أن يفعله:

```bash
echo 'fix' >> cart.py
git commit -am "fix(cart): keep quantities when a product price changes"
echo "patch only -> $(C --bumped-version 2>/dev/null)"
echo 'v2' >> README.md
git commit -am "feat(orders)!: amounts in GET /orders are integers in halalas" \
  -m "BREAKING CHANGE: total and vat were decimal riyals (12.5); they are now integer halalas (1250). Clients must divide by 100."
echo "breaking -> $(C --bumped-version 2>/dev/null)"
C --unreleased --bump
```

```text
patch only -> v1.4.1
breaking -> v2.0.0

### Added

- **BREAKING** orders: Amounts in GET /orders are integers in halalas

### Fixed

- cart: Keep quantities when a product price changes
```

والصورة التالية تلخص كيف وصلت الأداة إلى كل رقم من أنواع ال Commits:

![على اليمين قائمتان من ال Commits: منذ v1.3.0 فيها feat(cart) وfix(checkout) وdocs وupdate stuff بالأحمر وfix(auth)، ومنذ v1.4.0 فيها fix(cart) وfeat(orders)! بالأحمر. وعلى اليسار ثلاث نتائج: fix فقط يعطي PATCH من v1.4.0 إلى v1.4.1، وfeat واحد على الأقل يعطي MINOR من v1.3.0 إلى v1.4.0، وعلامة ! أو BREAKING CHANGE تعطي MAJOR من v1.4.0 إلى v2.0.0، وتحتها أن update stuff تجاهلتها الأداة رغم أنها غيرت حجم الصفحة من 20 إلى 50](https://arabroot.io/content/images/2026/11/semver-releases-02-commits-to-version.webp)

أعلى نوع منذ آخر Tag يحدد الرقم التالي

وفي الواقع لم يطلق الفريق 2.0.0 مباشرة، وإنما أطلق أولاً `2.0.0-rc.1` للشريك ليختبر عليه، ثم الإصدار النهائي بعد أن عدل الشريك كوده، مع إبقاء الإصدار 1.x يعمل على مسار مستقل مدة متفق عليها كما سيأتي في قسم إصدار ال API.

### ماذا لو كان المشروع على 0.x؟ What If

هذه تجربة من نوع «ماذا يحدث لو»: مشروع آخر للفريق ما زال على 0.3.0، فأضفنا إليه ميزة ثم تغييراً غير متوافق، وسألنا الأداة بإعدادها الافتراضي:

```bash
git commit --allow-empty -m "feat: first" && git tag v0.3.0
git commit --allow-empty -m "feat: add search";        echo "0.x feat -> $(C --bumped-version 2>/dev/null)"
git commit --allow-empty -m "feat!: rename all endpoints"; echo "0.x breaking -> $(C --bumped-version 2>/dev/null)"
```

```text
0.x feat -> v0.4.0
0.x breaking -> v1.0.0
```

أي أن الأداة بإعدادها الافتراضي قفزت بالمشروع إلى 1.0.0 بسبب تغيير غير متوافق، وهذا يعني إعلان الواجهة العامة مستقرة، وهو قرار يجب أن يتخذه الفريق بنفسه وليس أداة. وبحسب [توثيق إعداد الترقية في git-cliff](https://git-cliff.org/docs/configuration/bump?ref=arabroot.io) فإن الخيار `breaking_always_bump_major` قيمته الافتراضية true، وإذا جعلته false فإن التغيير غير المتوافق في 0.x يرفع الرقم الثانوي فقط:

```ini
[bump]
breaking_always_bump_major = false
features_always_bump_minor = true
```

```text
0.x breaking, breaking_always_bump_major=false -> v0.4.0
```

وهذا يتفق مع طريقة npm وCargo في معاملة الرقم الثاني في 0.x كأنه الرئيسي. والدرس أن كل أداة إطلاق آلي فيها قرارات افتراضية مثل هذا، فاقرأ صفحة إعداد الترقية قبل أن تضعها في خط CI، وجربها على مستودع تجريبي كما فعلنا.

### ماذا لو نقلت Tag بعد نشره؟ Moving a Released Tag

التجربة الأخيرة تخالف قاعدة SemVer الثالثة عن قصد. فلنفرض أن أحد أعضاء الفريق اكتشف بعد إطلاق 1.4.0 أن إصلاحاً صغيراً كان يجب أن يدخل فيه، فقرر أن ينقل ال Tag إلى Commit أحدث بدل أن يطلق 1.4.1\. أنشأنا مستودعاً بعيداً Remote ونسخة منه تمثل سيرفر CI، ثم نقلنا ال Tag:

```bash
git init --bare ../remote.git && git remote add origin ../remote.git
git push origin main v1.3.0 v1.4.0
git clone ../remote.git ../ci-clone             # CI has v1.4.0 -> 421beba
git tag -f -a v1.4.0 -m "shop-api 1.4.0 (re-tagged)" HEAD
git push origin v1.4.0
git push --force origin v1.4.0
cd ../ci-clone && git fetch --tags
```

```text
Updated tag 'v1.4.0' (was dc264d0)
 ! [rejected]        v1.4.0 -> v1.4.0 (already exists)
hint: Updates were rejected because the tag already exists in the remote.
 + dc264d0...994e9bb v1.4.0 -> v1.4.0 (forced update)
 ! [rejected]        v1.4.0     -> v1.4.0  (would clobber existing tag)
clone still sees v1.4.0 -> 421beba, remote has e977e02
```

![ثلاث خطوات: إعادة إنشاء ال Tag محلياً بالأمر git tag -f، ثم الدفع الذي رفضه السيرفر لأن ال Tag موجود ثم قبله مع --force، ثم نسخة CI القديمة التي رفضت التحديث لأن ال Tag موجود عندها وما زالت ترى 421beba والسيرفر يرى e977e02](https://arabroot.io/content/images/2026/11/semver-releases-07-moved-tag.webp)

نفس الاسم يشير إلى كودين مختلفين بحسب الجهاز

Git نفسه حاول أن يمنعنا مرتين: السيرفر رفض الدفع حتى أجبرناه بـ `--force`، والنسخة الموجودة على سيرفر CI رفضت أن تحدث ال Tag لأنه موجود عندها. والنتيجة الأسوأ من أي خطأ: الاسم `v1.4.0` يعني الآن كوداً على السيرفر وكوداً آخر على كل جهاز سحب قبل النقل، وأي Image بنيت من ال Tag قبل النقل تحمل الرقم نفسه وكوداً مختلفاً. ولا تقم بذلك أبداً، والسبب ما رأيته: لا يوجد طريقة لتعرف من لديه أي نسخة. والحل الصحيح دائماً إصدار جديد 1.4.1، فالأرقام مجانية.

## النطاقات Version Ranges في npm مع ملف القفل Lockfile

رأينا الإصدار من جهة من يطلقه، والآن من جهة من يستخدمه. ففي ملف `package.json` لا يكتب المطور رقماً واحداً لكل مكتبة غالباً، وإنما نطاقاً Range يقول أي الإصدارات يقبل، وأشهرها `^` التي يضعها npm افتراضياً عند التثبيت. ولكي نعرف بالضبط ماذا يقبل كل نطاق شغلنا سكربتاً صغيراً بالمكتبة [semver](https://github.com/npm/node-semver?ref=arabroot.io) التي يستخدمها npm نفسه، الإصدار 7.8.6، على Node.js 22:

```javascript
// Which versions does each npm range accept? (semver 7.8.6, the library npm itself uses)
const semver = require("semver");
const cases = [
  ["^1.4.0", ["1.4.1", "1.9.0", "2.0.0"]],
  ["~1.4.0", ["1.4.9", "1.5.0"]],
  ["^0.3.2", ["0.3.9", "0.4.0"]],
  ["^0.0.3", ["0.0.3", "0.0.4"]],
  ["^2.0.0", ["2.0.0-rc.1", "2.0.0"]],
  [">=1.4.0", ["2.0.0", "17.0.0"]],
];
for (const [range, versions] of cases)
  console.log(range.padEnd(8), versions.map(v => `${v} ${semver.satisfies(v, range) ? "yes" : "no"}`).join(" | "));
console.log("sorted:", semver.sort(["2.0.0", "2.0.0-rc.10", "2.0.0-rc.9", "2.0.0-alpha", "2.0.0-beta.2", "1.4.1"]).join("  <  "));
console.log("1.4.0+build.7 == 1.4.0+build.9 ?", semver.eq("1.4.0+build.7", "1.4.0+build.9"));
console.log("valid('v1.4') :", semver.valid("v1.4"), "  coerce('v1.4') :", semver.coerce("v1.4").version);
```

```bash
docker run --rm --name dvo-semver-node -v "$PWD/ranges.js:/w/ranges.js" -w /w node:22-slim \
  sh -c 'npm i -s --no-audit --no-fund semver@7.8.6 >/dev/null 2>&1; node -v; node ranges.js'
```

```text
v22.23.4
^1.4.0   1.4.1 yes | 1.9.0 yes | 2.0.0 no
~1.4.0   1.4.9 yes | 1.5.0 no
^0.3.2   0.3.9 yes | 0.4.0 no
^0.0.3   0.0.3 yes | 0.0.4 no
^2.0.0   2.0.0-rc.1 no | 2.0.0 yes
>=1.4.0  2.0.0 yes | 17.0.0 yes
sorted: 1.4.1  <  2.0.0-alpha  <  2.0.0-beta.2  <  2.0.0-rc.9  <  2.0.0-rc.10  <  2.0.0
1.4.0+build.7 == 1.4.0+build.9 ? true
valid('v1.4') : null   coerce('v1.4') : 1.4.0
```

![جدول النطاقات من المختبر: ^1.4.0 يقبل 1.4.1 و1.9.0 ويرفض 2.0.0، و~1.4.0 يقبل 1.4.9 ويرفض 1.5.0، و^0.3.2 يقبل 0.3.9 ويرفض 0.4.0 لأن الرقم الثاني في 0.x يعامل كأنه الرئيسي، و^0.0.3 يقبل 0.0.3 فقط، و^2.0.0 يرفض 2.0.0-rc.1، و>=1.4.0 يقبل 2.0.0 و17.0.0 وهذا خطر](https://arabroot.io/content/images/2026/11/semver-releases-03-ranges.webp)

ماذا يقبل كل نطاق في npm، من مخرج المختبر

ولنقرأ النتائج سطراً سطراً لأن كل سطر قرار يتخذه npm نيابة عنك:

- `^1.4.0` يقبل كل ما لا يغير الرقم الأول، أي أنه يثق بوعد SemVer كاملاً: كل إصدار ثانوي وكل إصلاح آمن. وهذا ما جعل is-promise 2.2.0 تصل إلى الجميع.
- `~1.4.0` يقبل الإصلاحات فقط، وهو الخيار الأحذر إذا كنت لا تثق بأن المكتبة تلتزم بالمواصفة في الإصدارات الثانوية.
- `^0.3.2` يرفض 0.4.0، وهذا تطبيق القاعدة التي ذكرناها: في 0.x الرقم الثاني هو الرئيسي عملياً. و`^0.0.3` لا يقبل إلا نفسه.
- `^2.0.0` يرفض `2.0.0-rc.1`، فالنسخ التجريبية لا تدخل إلا إذا كتبتها في النطاق صراحة، وهذا ما جعل المرشح آمناً للإطلاق في قصة الفريق.
- `>=1.4.0` يقبل حتى 17.0.0 التي لم تصدر بعد، أي أنك وافقت مسبقاً على كل تغيير غير متوافق في المستقبل، وهذا النطاق غير مناسب إطلاقاً لأي اعتماد في الإنتاج.
- آخر سطرين: بيانات البناء لا تدخل في المقارنة، والنص `v1.4` ليس رقم إصدار صحيحاً في المواصفة، والدالة `coerce` تخمن أنه 1.4.0\. فإذا كانت لديك أدوات تقرأ أرقاماً من مصادر مختلفة فلا تعتمد على التخمين.

وقد يتساءل البعض: إذا كان `^` يقبل أي إصدار ثانوي جديد، فكيف نضمن أن البناء اليوم يطابق البناء أمس؟ والإجابة هي ملف القفل [package-lock.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json?ref=arabroot.io)، الذي يحفظ الإصدار الدقيق لكل مكتبة مع بصمتها، والأمر [npm ci](https://docs.npmjs.com/cli/v11/commands/npm-ci?ref=arabroot.io) الذي يثبت ما في ملف القفل بالضبط ويفشل إذا اختلف عن `package.json`. أي أن النطاق يقول ما تقبله عندما تقرر أن تحدث، وملف القفل يقول ما تستخدمه الآن، والتحديث يصبح قراراً له Commit يمر بالاختبارات، وأدوات مثل Renovate تفتح لك طلب دمج لكل تحديث. ولذلك القاعدة: ملف القفل يدخل Git دائماً، وخط CI يستخدم `npm ci` وليس `npm install`.

وفي 22 مارس 2016 رأى مجتمع JavaScript كله ماذا يعني أن تعتمد على إصدارات لا تتحكم فيها، فقد حذف مطور مكتبة صغيرة اسمها left-pad، مع 272 مكتبة أخرى له، من سجل npm بعد خلاف على اسم مكتبة أخرى، فتوقف بناء آلاف المشاريع التي تعتمد عليها بشكل مباشر أو غير مباشر، كما شرحت npm في [تدوينتها عن الحادثة](https://blog.npmjs.org/post/141577284765/kik-left-pad-and-npm?ref=arabroot.io)، وأعادت npm نشر المكتبة بعد ساعات وغيرت بعد ذلك [سياسة حذف المكتبات](https://docs.npmjs.com/policies/unpublish?ref=arabroot.io) فأصبح الحذف بعد 72 ساعة من النشر مقيداً بشروط. والدرس للفريق: الإصدار المنشور يجب أن يبقى كما هو وفي مكانه، وهذا ما تقوله قاعدة SemVer الثالثة من جهة أخرى.

## من الأحدث؟ ترتيب الإصدارات Version Sorting

سؤال يبدو بسيطاً ولكنه قد يكلفك يوماً من التحقيق إذا أخطأت فيه أداة الإطلاق: ما هو آخر إصدار؟ فقد أنشأنا في المستودع التجريبي وسوماً لعدة إصدارات وطلبنا من Git أن يعرضها بثلاث طرق:

```bash
for t in v1.9.0 v1.10.0 v1.2.0 v2.0.0-rc.1 v2.0.0; do git tag $t; done
git tag -l
git tag -l --sort=v:refname
git -c versionsort.suffix=-rc tag -l --sort=v:refname
```

```text
v0.3.0 v1.10.0 v1.2.0 v1.9.0 v2.0.0 v2.0.0-rc.1
v0.3.0 v1.2.0 v1.9.0 v1.10.0 v2.0.0 v2.0.0-rc.1
v0.3.0 v1.2.0 v1.9.0 v1.10.0 v2.0.0-rc.1 v2.0.0
```

![ثلاثة صناديق: git tag -l يرتب الحروف فيضع v1.10.0 قبل v1.2.0، و--sort=v:refname يرتب الأرقام ولكنه يضع v2.0.0-rc.1 بعد v2.0.0، وversionsort.suffix=-rc يعطي الترتيب الصحيح، وتحتها ترتيب semver.sort في npm من 1.4.1 إلى 2.0.0-alpha ثم beta.2 ثم rc.9 ثم rc.10 ثم 2.0.0](https://arabroot.io/content/images/2026/11/semver-releases-04-sort.webp)

ترتيب النصوص ليس ترتيب الإصدارات

الترتيب الافتراضي ترتيب حروف، فيضع 1.10.0 قبل 1.2.0 لأن الحرف «1» قبل «2». والخيار `v:refname` يرتب الأرقام كأرقام، ولكنه لا يعرف أن `-rc.1` تعني نسخة قبل الإصدار، فيضعها بعد 2.0.0، وأي سكربت يأخذ آخر سطر على أنه آخر إصدار سوف ينشر المرشح بدل الإصدار النهائي. والإعداد `versionsort.suffix` يخبر Git أن اللاحقة `-rc` قبل الإصدار، فيصبح الترتيب صحيحاً. وأفضل من كل ذلك أن تستخدم في سكربتاتك أداة تفهم SemVer فعلاً، مثل `semver.sort` التي رأيت مخرجها في القسم السابق، أو git-cliff نفسها التي تحسب آخر إصدار بقواعد المواصفة.

## وسوم ال Docker Image: Docker Tags

الخدمة `shop-api` تنشر في النهاية Docker Image، ووسوم ال Image Tags تتبع عادة رقم الإصدار، ولكن بطريقة تختلف عن Git في نقطة مهمة: وسم Docker يتحرك بطبيعته، فهو اسم يشير إلى Image، ويمكن أن تنقله إلى Image أخرى في أي وقت بالأمر [docker tag](https://docs.docker.com/reference/cli/docker/image/tag/?ref=arabroot.io). والممارسة الشائعة في المشاريع الكبيرة، ومنها Images الرسمية مثل PostgreSQL وPython، أن تنشر لكل إصدار ثلاثة وسوم: الرقم الكامل `1.4.1`، والرقم الثانوي `1.4`، والرئيسي `1`، والوسمان الأخيران ينتقلان مع كل إصدار جديد. وقد جربنا ذلك بإصدارين:

```bash
for v in 1.4.0 1.4.1; do
  printf 'FROM python:3.13-slim\nLABEL org.opencontainers.image.version="%s"\nRUN echo %s > /VERSION\n' $v $v > Dockerfile
  docker build -q -t dvo-semver-api:$v .
  docker tag dvo-semver-api:$v dvo-semver-api:1.4
  docker tag dvo-semver-api:$v dvo-semver-api:1
  echo "== after $v"; docker images dvo-semver-api --format '{{.Tag}}\t{{.ID}}' | sort
done
docker run --rm dvo-semver-api:1.4 cat /VERSION
docker run --rm dvo-semver-api:1.4.0 cat /VERSION
```

```text
== after 1.4.0
1       cfc0fa320f68
1.4     cfc0fa320f68
1.4.0   cfc0fa320f68
== after 1.4.1
1       3bcbfff9365d
1.4     3bcbfff9365d
1.4.0   cfc0fa320f68
1.4.1   3bcbfff9365d
1.4.1
1.4.0
```

![بعد بناء 1.4.0 تشير الوسوم 1.4.0 و1.4 و1 إلى cfc0fa320f68، وبعد بناء 1.4.1 ينتقل الوسمان 1.4 و1 إلى 3bcbfff9365d ويبقى 1.4.0 على الأولى، وتحتها: للإنتاج الرقم الكامل أو البصمة sha256، وللتجربة 1.4 أو 1، ولا تستخدم latest في الإنتاج](https://arabroot.io/content/images/2026/11/semver-releases-05-docker-tags.webp)

الوسمان 1.4 و1 ينتقلان، و1.4.0 يبقى

والوسم `1.4` كان يشير إلى 1.4.0 ثم أصبح يشير إلى 1.4.1 دون أن يغير أحد ملف Compose، وهذا مفيد إذا كنت تريد الإصلاحات تلقائياً في بيئة تجريبية، وخطير في الإنتاج لأن نفس الملف يعني Image مختلفة بحسب وقت السحب. ولذلك القاعدة التي اتبعناها في مقالات الموقع كلها: في الإنتاج استخدم الرقم الكامل دائماً، والأفضل البصمة Digest بالشكل `image@sha256:...` لأنها الوحيدة التي لا يمكن أن تتغير أبداً، حتى لو نقل أحد الوسم الكامل نفسه في ال Registry. وأضفنا كذلك التسمية `org.opencontainers.image.version` داخل ال Image، فيعرف من يفحصها رقمها حتى لو وصلته بوسم آخر.

## خطوات الإطلاق في CI: Release Process

كل ما فعلناه يدوياً في المختبر يجب أن يتحول إلى خطوات آلية، والسبب أن الإطلاق اليدوي يعتمد على ذاكرة الشخص الذي يقوم به، فينسى تحديث `package.json` مرة، ويكتب Tag خفيفاً مرة، ويبني ال Image من فرعه المحلي مرة. والصورة التالية تبين الخطوات بالترتيب كما طبقها الفريق:

![ست خطوات: الفحص في CI أن كل Commit بصيغة Conventional Commits، ثم حساب الرقم التالي بالأمر git cliff --bumped-version، ثم سجل التغييرات يراجعه إنسان، ثم Commit الإطلاق chore(release) مع الرقم في package.json، ثم Tag مشروح لا يتحرك، ثم البناء والنشر بالوسوم 1.4.0 و1.4 و1 وملاحظات الإصدار](https://arabroot.io/content/images/2026/11/semver-releases-06-release-flow.webp)

من آخر Commit إلى الإصدار المنشور

والتطبيق العملي الذي اختاره الفريق على [Gitea Actions](https://arabroot.io/articles/gitea-actions-%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-ci-cd-%D8%B9%D9%84%D9%89-%D8%AE%D8%A7%D8%AF%D9%85%D9%83/) كما يلي: كل طلب دمج يمر بفحص صيغة ال Commits، ومع كل دمج في الفرع الرئيسي تفتح أداة الإطلاق طلب دمج خاصاً اسمه «Release 1.5.0» يحتوي السجل المقترح وتحديث الرقم، فيقرؤه أحد أعضاء الفريق ويعدل فيه إذا لزم، ثم يدمجه، وعند الدمج يعمل خط آخر ينشئ ال Tag ويبني ال Image وينشر ملاحظات الإصدار. وبهذا يبقى القرار عند الإنسان، أي متى نطلق وكيف نصف التغييرات، والتنفيذ عند الآلة. وأدوات مثل release-please وsemantic-release تفعل هذا المسار كاملاً، ومع git-cliff تبنيه أنت بخطوات قليلة في أي سيرفر CI.

### إصلاح إصدار قديم Hotfix على فرع الصيانة

بعد إطلاق 2.0.0 اكتشف الفريق ثغرة في المصادقة موجودة في 1.4.x أيضاً، والشريك ما زال على 1.x حتى ينتهي من تعديل كوده. والحل في SemVer واضح: الإصلاح يطلق في الإصدارين، 2.0.1 للفرع الرئيسي و1.4.2 للفرع القديم. ولذلك ينشئ الفريق فرع صيانة من ال Tag القديم، مثل `release/1.4`، ويطبق عليه الإصلاح بالأمر `git cherry-pick` الذي شرحناه في [مقال merge مع rebase](https://arabroot.io/articles/git-merge-%D9%88-rebase-%D9%88-cherry-pick/)، ثم يطلق منه 1.4.2 بنفس الخطوات. ولاحظ أن الأداة تحسب الرقم من آخر Tag يمكن الوصول إليه من الفرع الحالي، فعلى فرع الصيانة يكون آخر Tag هو v1.4.1 وليس v2.0.0، وهذا ما يجعل الرقم 1.4.2 صحيحاً تلقائياً.

## إصدار الخدمة وإصدار ال API Versioning

هناك خلط شائع بين رقمين مختلفين في الخدمات: رقم إصدار الخدمة نفسها، مثل `shop-api 2.0.0`، ورقم إصدار ال API الذي يظهر في العنوان مثل `/v1/orders` و`/v2/orders`. والأول يتغير مع كل إطلاق ويقرؤه الفريق والعمليات، والثاني يتغير نادراً جداً، ويقرؤه العملاء، ومعناه «عقد» يبقى ثابتاً سنوات. والسبب أن تطبيق الجوال لا يتحدث عند كل المستخدمين في يوم واحد، فهناك مستخدمون سوف يبقون على النسخة القديمة من التطبيق أشهراً، ولذلك لا يكفي أن تطلق 2.0.0 وتقول للجميع عدلوا كودكم، وإنما تحتاج أن تبقي المسار القديم يعمل.

وما فعله الفريق مع تغيير المبالغ هو الشكل الشائع: الإصدار 2.0.0 من الخدمة أضاف المسار `/v2/orders` بالهللات، وأبقى `/v1/orders` بالريالات يعمل بنفس الكود، مع إضافة ترويسة Header في الردود القديمة تخبر العميل بأن المسار سوف يتوقف في تاريخ محدد، وسجل الفريق المسار القديم في قسم Deprecated من سجل التغييرات، وبعد المدة المتفق عليها أطلق إصداراً رئيسياً آخر يحذف المسار القديم ويسجله في قسم Removed. وبهذا تبقى قاعدة SemVer صحيحة على مستوى الخدمة، ويبقى العقد ثابتاً على مستوى العملاء.

## أخطاء شائعة Common Mistakes

- **رفع الرقم الأخير مع كل نشر:** الرقم يصبح عداداً لا يقول شيئاً، والتغيير غير المتوافق يبدو مثل الإصلاح.
- **تغيير غير متوافق برقم ثانوي:** كما حدث مع is-promise، والحل إصدار جديد يعيد التوافق وليس تعديل المنشور.
- **نقل Tag أو إعادة نشر رقم:** نفس الاسم يصبح كودين مختلفين، والحل رقم جديد دائماً.
- **سجل Git بدل سجل التغييرات:** القارئ لا يجد ما يهمه بين رسائل المطورين.
- **سجل مولد دون مراجعة:** الأداة تسكت عن ال Commits التي لا تفهمها، كما رأينا مع «update stuff».
- **الاعتماد على الإعداد الافتراضي لأداة الإطلاق:** مثل الانتقال إلى 1.0.0 بسبب تغيير واحد في 0.x.
- **ترتيب الوسوم كنصوص:** فيصبح 1.10.0 أقدم من 1.2.0، والمرشح أحدث من الإصدار.
- **`latest` أو `1` في الإنتاج:** نفس الملف يعني Image مختلفة بعد كل سحب.
- **النطاق `>=` أو `*` في الاعتمادات:** موافقة مسبقة على كل تغيير غير متوافق في المستقبل.
- **ملف القفل خارج Git أو `npm install` في CI:** البناء اليوم يختلف عن البناء أمس دون أي Commit.
- **البقاء على 0.x سنوات مع مستخدمين في الإنتاج:** تهرب من الالتزام لا يحمي أحداً.
- **خلط رقم الخدمة برقم ال API:** فيصبح كل إطلاق مساراً جديداً للعملاء، أو لا يتغير المسار مع تغيير غير متوافق.

## قائمة تحقق Checklist للإطلاق

| البند                         | كيف تتحقق منه                                                         |
| ----------------------------- | --------------------------------------------------------------------- |
| الواجهة العامة موثقة          | صفحة تقول ما هو مضمون وما هو غير مضمون، مثل حجم الصفحة والترتيب       |
| كل Commit بنوع                | فحص Conventional Commits في CI على كل طلب دمج                         |
| الرقم التالي يحسب ولا يخمن    | git cliff --bumped-version أو أداة مثلها، مع مراجعة إعداد الترقية     |
| السجل بأقسام Keep a Changelog | Added وChanged وDeprecated وRemoved وFixed وSecurity، وقسم Unreleased |
| إنسان يراجع السجل قبل الإطلاق | طلب دمج للإطلاق يقرؤه عضو في الفريق                                   |
| Tag مشروح لكل إصدار           | git cat-file -t v1.4.0 يعطي tag وليس commit                           |
| لا يتحرك أي Tag منشور         | حماية الوسوم في سيرفر Git، ومنع \--force عليها                        |
| ال Image تحمل رقمها           | الوسم الكامل والتسمية org.opencontainers.image.version                |
| الإنتاج على رقم كامل أو بصمة  | لا يوجد latest ولا 1 في ملفات الإنتاج                                 |
| الاعتمادات مقفلة              | ملف القفل في Git، وnpm ci في CI، والتحديثات بطلبات دمج                |
| التغيير غير المتوافق له خطة   | نسخة \-rc للعملاء، ومسار قديم يعمل مدة معلنة، وقسم Deprecated         |

## تدريب عملي Practice

- أنشئ فرع صيانة `release/1.4` من `v1.4.0` في مستودع المختبر، وطبق عليه إصلاح السلة بالأمر `git cherry-pick`، ثم تأكد أن `git cliff --bumped-version` يعطي `v1.4.1` على هذا الفرع.
- أضف إلى السكربت `ranges.js` النطاق `^2.0.0-rc.1`، وتأكد هل يقبل `2.0.0-rc.2` و`2.1.0-rc.1`، ثم اقرأ قسم النسخ التجريبية في [توثيق المكتبة](https://github.com/npm/node-semver?ref=arabroot.io) لتعرف السبب.

## حذف المختبر Cleanup

```bash
docker rmi dvo-semver-api:1.4.0 dvo-semver-api:1.4.1 dvo-semver-api:1.4 dvo-semver-api:1
docker rmi orhunp/git-cliff:2.14.2
rm -rf shop-api zero remote.git ci-clone
```

## الخلاصة Summary

وصلنا لنهاية الموضوع، وأهم ما فيه:

- رقم الإصدار لغة مشتركة بين من يطلق ومن يستخدم، وفي SemVer كل جزء وعد: الإصلاح آمن، والثانوي آمن ومعه جديد، والرئيسي يحتاج تعديلاً.
- الواجهة العامة أوسع من التوثيق بحسب قانون Hyrum، وis-promise 2.2.0 مثال على تغيير غير متوافق برقم ثانوي، والإصلاح دائماً إصدار جديد.
- Conventional Commits تجعل الرقم التالي حساباً، وgit-cliff حسبه في المختبر 1.4.0 ثم 1.4.1 ثم 2.0.0، ولكن ال Commit بلا نوع اختفى من السجل بتحذير واحد حتى أجبرنا الأداة على الفشل.
- أدوات الإطلاق لها قرارات افتراضية ومشاكل خاصة، مثل الانتقال إلى 1.0.0 من 0.x وسكربت ال Image الذي يقطع المعاملات عند المسافات، فجربها قبل أن تعتمد عليها.
- ال Tag المنشور لا يتحرك، والنطاق `^` مع ملف القفل يعطيك التحديث بقرار، وترتيب الإصدارات ليس ترتيب نصوص، والإنتاج على رقم كامل أو بصمة.

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

[![](https://arabroot.io/content/images/2026/11/env-config-cover-cover.webp)دليلمتغيرات البيئة Environment Variables: تطبيق واحد لكل البيئاتكيف يقرأ تطبيقك إعداده من الخارج ويتحقق منه عند التشغيل، فتنتقل Image واحدة بين كل البيئات دون أي سر في الكود.](https://arabroot.io/articles/%D9%85%D8%AA%D8%BA%D9%8A%D8%B1%D8%A7%D8%AA-%D8%A7%D9%84%D8%A8%D9%8A%D8%A6%D8%A9-environment-variables-%D8%AA%D8%B7%D8%A8%D9%8A%D9%82-%D9%88%D8%A7%D8%AD%D8%AF-%D9%84%D9%83%D9%84-%D8%A7%D9%84%D8%A8%D9%8A%D8%A6%D8%A7%D8%AA/)[![](https://arabroot.io/content/images/2026/10/environments-gitops-cover-cover.webp)دليلمن الفرع إلى الإنتاج: البيئات وGitOps للفرقكيف يختبر فريقك كل ميزة وحدها ويعرضها على العميل دون أن تصل ميزة غير جاهزة إلى الإنتاج.](https://arabroot.io/articles/%D8%A7%D9%84%D8%A8%D9%8A%D8%A6%D8%A7%D8%AA-%D9%88%D9%85%D8%B9%D8%A7%D9%8A%D9%86%D8%A9-%D8%A7%D9%84%D9%85%D9%8A%D8%B2%D8%A7%D8%AA-%D9%88-gitops-%D9%84%D9%84%D9%81%D8%B1%D9%82/)[![](https://arabroot.io/content/images/2026/10/gitea-actions-cover-cover-2.webp)دليلGitea Actions: تشغيل CI/CD وبناء Docker Images على سيرفركاجعل سيرفرك يختبر الكود ويبني Docker Images تلقائياً مع كل push، دون أن يخرج كودك أو أسرارك إلى خدمة CI خارجية.](https://arabroot.io/articles/gitea-actions-%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-ci-cd-%D8%B9%D9%84%D9%89-%D8%AE%D8%A7%D8%AF%D9%85%D9%83/)[![](https://arabroot.io/content/images/2026/10/git-workflows-cover-cover.webp)دليلGit في العمل اليومي: الدمج والتراجع دون أن تخسر عملكمتى تستخدم Merge ومتى تستخدم Rebase، وكيف تنقل إصلاحاً إلى فرع الإصدار أو تسترجع عملاً ظننت أنه ضاع.](https://arabroot.io/articles/git-merge-%D9%88-rebase-%D9%88-cherry-pick/)[![](https://arabroot.io/content/images/2026/10/feature-flags-cover-cover.webp)دليلFeature Flags: انشر الكود وفعل الميزة لاحقاًكيف يفصل ال Feature Flag بين نشر الكود وإطلاق الميزة، وكيف تطلقها لجزء من المستخدمين أولاً وتوقفها فوراً إذا تعطلت.](https://arabroot.io/articles/%D9%85%D9%81%D9%87%D9%88%D9%85-feature-flags-%D9%88%D8%A7%D9%84%D8%A7%D8%B7%D9%84%D8%A7%D9%82-%D8%A7%D9%84%D8%AA%D8%AF%D8%B1%D9%8A%D8%AC%D9%8A-gradual-rollout/)

## سجل التحديثات Changelog

- نوفمبر 2026: كتابة الدليل وتنفيذ المختبر بإصدارات git-cliff 2.14.2 وGit 2.48.1 وsemver 7.8.6 على Node.js 22.23.4 وDocker Engine 29.8.0.