پرش به محتوای اصلی

راهنمای ماشین‌حساب نسخه (semver)

زمان مطالعه: ۲ دقیقه

این ابزار چیست؟

نسخه‌گذاری معنایی (semver) شماره‌ی نسخه را سه بخش می‌کند: MAJOR.MINOR.PATCH. تغییر بخش اول یعنی ناسازگاری، بخش دوم یعنی قابلیت تازه‌ی سازگار و بخش سوم یعنی رفع اشکال. npm، Composer، Cargo و بسیاری از ابزارهای دیگر با همین قاعده و بازه‌هایی مثل ^1.2.3 یا ~2.1.0 تصمیم می‌گیرند کدام نسخه را نصب کنند؛ و خواندن این بازه‌ها همیشه ساده نیست.

این ماشین‌حساب فهرست نسخه‌ها را مرتب می‌کند، معنای یک بازه را به شکل استاندارد باز می‌کند، نشان می‌دهد کدام نسخه‌ها در بازه می‌افتند، دو نسخه را مقایسه می‌کند و نسخه‌ی بعدی را می‌سازد. محاسبه با همان کتابخانه‌ی semver که npm به کار می‌برد و در مرورگر شما انجام می‌شود.

گام‌به‌گام

  1. فهرست نسخه‌ها را بنویسید

    در «فهرست نسخه‌ها و بازه» هر نسخه را در یک سطر یا با فاصله و ویرگول جدا بنویسید. نسخه‌های نامعتبر جدا مشخص می‌شوند.

  2. بازه را وارد کنید

    در «بازه (range)» عبارتی مثل ^1.2.3، ~2.1.0، >=1.0.0 <2.0.0 یا 1.x بنویسید؛ «شکل استاندارد» معنای دقیق آن را نشان می‌دهد.

  3. نتیجه‌ی مطابقت را ببینید

    هر نسخه برچسب «مطابق است» یا «مطابق نیست» می‌گیرد و بالاترین نسخه‌ی مطابق مشخص می‌شود. پیش‌انتشارها فقط با «شامل پیش‌انتشار» حساب می‌شوند.

  4. دو نسخه را مقایسه کنید

    دو نسخه را بنویسید تا ببینید کدام جدیدتر است و تفاوتشان در کدام بخش است.

  5. نسخه‌ی بعدی را بسازید

    در «افزایش نسخه» نسخه‌ی فعلی و نوع افزایش را انتخاب کنید؛ برای پیش‌انتشار یک برچسب مثل beta بدهید.

نمونه‌های کاربردی

  • بازه‌ی تیلدا

    ~2.1.0 فقط رفع اشکال‌های 2.1 را می‌پذیرد؛ 2.2.0 بیرون است و پیش‌انتشار هم به‌طور پیش‌فرض کنار می‌رود.

    2.1.0
    2.1.9
    2.2.0
    2.1.5-beta.1

    نتیجه: مطابق: 2.1.0 و 2.1.9 · بالاترین: 2.1.9

  • معنای بازه‌ی کلاهک

    ^1.2.3 هر نسخه‌ی سازگار با 1 را از 1.2.3 به بعد می‌پذیرد، اما 2.0.0 را نه.

    1.2.3
    1.9.0
    2.0.0

    نتیجه: >=1.2.3 <2.0.0-0

اشتباه‌های رایج

  • مرتب کردن نسخه‌ها مثل متن: به شکل متنی 1.10.0 پیش از 1.9.3 می‌آید، اما در semver جدیدتر است. فهرست را به همین ابزار بدهید تا درست مرتب شود.
  • فرض اینکه ^0.2.3 مثل ^1.2.3 رفتار می‌کند: برای نسخه‌های زیر ۱، کلاهک سخت‌گیرتر است و فقط 0.2.x را می‌پذیرد.
  • انتظار پیش‌انتشار در بازه‌ی معمولی: 2.1.5-beta.1 در ~2.1.0 نمی‌افتد مگر «شامل پیش‌انتشار» روشن باشد.
  • بالا بردن MINOR برای تغییر ناسازگار: کسانی که ^ به کار برده‌اند نسخه‌ی تازه را خودکار می‌گیرند و برنامه‌شان می‌شکند. تغییر ناسازگار یعنی MAJOR تازه.

کلاهک و تیلدا

^ یعنی «سازگار با»: بخش غیرصفرِ سمت چپ ثابت می‌ماند و بقیه می‌تواند بالا برود. پس ^1.2.3 تا پیش از 2.0.0 را می‌پذیرد و ^0.2.3 تا پیش از 0.3.0 را. ~ یعنی «تقریباً»: فقط بخش PATCH بالا می‌رود، پس ~2.1.0 تا پیش از 2.2.0 است.

شکل استاندارد بازه با پسوند -0 نوشته می‌شود، مثل <2.0.0-0، تا پیش‌انتشارهای 2.0.0 هم بیرون بمانند. این همان چیزی است که npm هنگام نصب حساب می‌کند.

پرسش‌های متداول

تفاوت ^ و ~ چیست؟
^1.2.3 یعنی از 1.2.3 تا قبل از 2.0.0 و ~1.2.3 یعنی از 1.2.3 تا قبل از 1.3.0. برای نسخه‌های 0.x کاراکتر ^ سخت‌گیرانه‌تر است: ^0.2.3 فقط تا قبل از 0.3.0 را می‌پذیرد.
چرا نسخه‌ی پیش‌انتشار با بازه مطابق نمی‌شود؟
طبق قرارداد semver، نسخه‌ی پیش‌انتشار (مثل 2.0.0-beta.1) فقط وقتی با بازه مطابق است که خود بازه هم برای همان نسخه‌ی اصلی پیش‌انتشار داشته باشد. گزینه‌ی «شامل پیش‌انتشار» این قاعده را برمی‌دارد.
پیشوند v یا فاصله مشکلی دارد؟
پیشوند v مثل v1.2.3 پذیرفته می‌شود. نسخه‌های نامعتبر جدا و با علت فهرست می‌شوند.

ابزارهای مرتبط