محلّل ومقارن إصدارات SemVer

ما هو مُحلِّل الإصدار الدلاليّ؟#

الإصدار الدلاليّ (SemVer) اصطلاح major.minor.patch الذي تستخدمه معظم المكتبات للإشارة إلى نوع التغيير في إصدار: إصلاح ثُغرة يرفع patch، والإضافات المتوافقة مع الخلف ترفع minor، والتغييرات الكاسرة ترفع major. أضِف وسمَ ما قبل الإصدار (1.0.0-beta.1) أو بيانات البناء الوصفية (+exp.sha.1) فتحصل على القواعد الكاملة المُعرَّفة في semver.org 2.0.0.

المشكلة أنّ «قارن إصدارَين» و«هل يُرضي هذا الإصدار نطاق تبعيتي» يسهل الخطأ فيهما بالعين. هل 1.0.0 أعلى أمأدنى من 1.0.0-beta؟ (أعلى — فالإصدار يفوق ما قبل إصداره دائمًا.) هل يُرضي 1.2.3 الشرط ^1.2.0؟ (نعم.) هل يُرضي ~1.2.0؟ (نعم أيضًا، لكن لسببٍ أمكر.) تُحلِّل هذه الصفحة الإصدارات كما تُعرِّفها المواصفة، وتُريك المكوّنات، وتقارن إصدارَين بالأسبقية، وتُجيب عن استعلامات النطاق بالصيغة ^ / ~ / >= / || / الواصلة نفسها التي يستخدمها package.json — كلّ ذلك محليًّا، وفق القواعد الحقيقية لا تخمينًا.

كيفية الاستخدام#

1. استخدم أزرار الملء السريع في الأعلى لإسقاط أمثلة شائعة، أواكتب مباشرةً.
2. أدخل الإصدار A والإصدار B في المُدخلَين. تُقبل البادئة v أو= وتُزال؛ ويُحلَّل 1.2.3-beta.1+build.42 إلى أجزائه.
3. أدخل تعبير نطاق إن أردت فحص إرضاء. الافتراضي ^1.2.0 || >=2.0.0 <3.0.0 — مجموعتا OR، كما تُكتب نطاقات التبعية الحقيقية. الصيغ المدعومة: ^ (caret)، ~ (تيلدة)، >= <= > < =، البدل x / X / *، الإصدارات الجزئية (1.2)، نطاقات الواصلة -، و|| لـ OR بين المجموعات.
4. اقرأ بطاقتَي التحليل. كلٌّ تُظهر الصيغة القياسية clean والحقول المُفرَّقة major وminor وpatch وprerelease وbuild. والإصدار غير الصالح يحوّل بطاقته حمراء مع رسالة.
5. اقرأ بطاقة المقارنة. تعرض A < B أوA = B أوA > B بالأسبقية، بالإضافة إلى diff — أعلى مكوّن تغيّر (major أوminor أوpatch أوprerelease أوbuild).
6. اقرأ بطاقة فحص النطاق. تُخبرك، للنطاق الذي كتبته، هل يُرضيه A وهل يُرضيه B.

الميزات الرئيسية#

• الأسبقية وفق المواصفة. تطأ المقارنة major.minor.patch ثمّ مُعرِّفات ما قبل الإصدار، مع القاعدة أنّ إصدارًا بلا ما قبل إصدار يفوق دائمًا واحدًا به. المعرِّفات الرقمية تُقارَن رقميًّا (beta.2 < beta.11)؛ والأبجدية الرقمية تُقارَن معجميًّا؛ والرقميّ دائمًا أدنى من الأبجديّ الرقميّ. metadata البناء تُحلَّل وتُعرَض لكنها لا تُؤثّر في الأسبقية أبدًا.
• الرمز ^ والتيلدة، مُزالَتا السكر بشكل صحيح. يُصبح ^1.2.3 هو >=1.2.3 <2.0.0؛ و^0.2.3 هو >=0.2.3 <0.3.0؛ و^0.0.3 هو >=0.0.3 <0.0.4 — قاعدة الـ caret «أبعد غير صفريّ يسارًا». والتيلدة تُثبّت minor نفسها: ~1.2.3 هي >=1.2.3 <1.3.0.
• النطاقات بـ || والواصلات والبدائل. ^1.0.0 || >=2.0.0 <3.0.0 (OR لمجموعتَين)، و1.2.0 - 1.5.0 (نطاق واصلة شامل)، و1.x / 1.2.* (نطاقات بديلة) كلّها تُحلَّل وتُفحَص.
• بوابة إدراج ما قبل الإصدار. يُرضي إصدار ما قبل الإصدار نطاقًا فقط حين يحمل مقارِنٌ ما في المجموعة نفسها وسمَ ما قبل إصدار على major.minor.patch نفسها. فـ 1.5.0-rc.1 لا يُرضي ^1.2.0، لكنه يُرضي ^1.5.0-rc.0 — مطابقاً لكيفية إبقاء مديري الحزم الحقيقيّين ما قبل الإصدارات العشوائية خارج بناءات إصدارك.
• فرقٌ يحكي قصة. يُبلّغ حقل diff أعلى مكوّن تغيّر، فقفزةٌ من 1.2.3 إلى 2.0.0 تُظهر major، ومن 1.0.0 إلى 1.0.0 مع بناء متغيّر تُظهر build رغم أنّ الأسبقية لم تتغيّر.
• مُدخل متساهل. تُقبَل v البادئة، و= البادئة، والفراغ المحيط، فتُحلَّل الإصدارات المنسوخة من وسم git أوسجلّ تغييرات دون تنظيف يدويّ.

مثال عملي#

بالافتراضات — A 1.2.3 وB 2.0.0 والنطاق ^1.2.0 || >=2.0.0 <3.0.0 — تُبلّغ الصفحة:

A clean    1.2.3        (major 1, minor 2, patch 3)
B clean    2.0.0        (major 2, minor 0, patch 0)
compare    1.2.3  <  2.0.0
diff       major
range      A satisfies   B satisfies

كلّ إصدارٍ يُرضي النطاق، لكن لأسباب مختلفة: A يقع داخل مجموعة OR الأولى (^1.2.0 → >=1.2.0 <2.0.0)، وB يقع داخل الثانية (>=2.0.0 <3.0.0). غيّر B إلى 3.0.0 فتقلب شارته إلى not satisfies — الحدّ الأعلى <3.0.0 يستثنيها.

لرؤية قاعدة ما قبل الإصدار في العمل، اضبط A على 1.5.0-rc.1 وB على 1.5.0، وابقِ النطاق ^1.5.0-rc.0. الآن A يُرضي (الـ 1.5.0 نفسها، النطاق يحمل وسمَ ما قبل إصدار مطابق)، بينما ^1.5.0 المجرّد لن يُمرِّر 1.5.0-rc.1 — البابة موجودة بالضبط لإبقاء مرشحي الإصدار خارج حلّ تبعيات الإصدار حتى تشترك.

الأسئلة الشائعة#

هل 1.0.0 أعلى من 1.0.0-beta؟#

نعم. الإصدار بلا وسم ما قبل إصدار تكون أسبقيّته دائمًا أعلى من واحدٍ بوسم ما قبل إصدار، حتى عند major.minor.patch نفسها. فـ 1.0.0 > 1.0.0-rc.1 > 1.0.0-beta.11 > 1.0.0-alpha. ولهذا فإنّ إصدارًا «يبلغ الذهبيّ» قفزة أسبقية حقيقية، لا مجرّد تغيير وسم.

ما الفرق بين ^ و~؟#

رمز الـ caret يسمح بالتحديثات التي لا تُعدِّل المكوّن غير الصفريّ الأبعد يسارًا: ^1.2.3 يسمح بأيّ 1.x.x من 1.2.3 حتى (دون إشراك) 2.0.0. والتيلدة أمصر — تُثبّت minor عند إعطائها إصدارًا كاملًا: ~1.2.3 يسمح فقط بـ 1.2.x. وعند إعطائها major فقط (~1)، فالتيلدة والرمز ^ معًا يسمحان بمجال major الكامل. معظم المكتبات تُثبّت بـ ^؛ ورفع إصدار الحزمة المنشورة نفسها كثيرًا ما يستخدم ~.

لماذا لا يُرضي إصدار ما قبل إصدار ^1.0.0؟#

بالتصميم. لا يُرضي ما قبل إصدارٍ مثل 1.5.0-rc.1 نطاقًا إلا حين يكون لمقارِنٍ ما في مجموعة AND نفسها وسم ما قبل إصدار على 1.5.0 نفسها. و^1.0.0 يُزال سكره إلى >=1.0.0 <2.0.0-0 بلا ما قبل إصدار على 1.5.0، فتبقي البابة بناء إصدارك من سحب مرشّح إصدارٍ عشوائيّ لأحد. وإن أردت الاشتراك فاكتب ^1.5.0-rc.0 صراحةً.

هل تُؤثّر metadata البناء في المقارنة؟#

لا. 1.0.0+exp.sha.5 و1.0.0+exp.sha.6 لهما أسبقية متساوية — metadata البناء للتعريف فقط. يُظهرها المُحلِّل مع ذلك (ويُبلّغ diff عن تغيّر build حين لا يختلف سواه)، لكنها لا تُقرّر ترتيبًا قطّ.