نسخه‌بندی معنایی (SemVer)؛ رمزگشایی اعداد وابستگی‌های پروژه

عدد ۲.۱۴.۳ یعنی چه؟

هر پکیجی که نصب می‌کنید، سه عدد دارد که با نقطه جدا می‌شوند: نسخهٔ اصلی.فرعی.اصلاحی یا MAJOR.MINOR.PATCH. عدد سوم (PATCH) یعنی رفع باگ بدون هیچ تغییرِ رفتاری؛ عدد وسط (MINOR) یعنی قابلیت جدیدی اضافه شده اما کدهای قبلی قرار نیست بشکنند؛ و عدد اول (MAJOR) یعنی چیزی تغییر کرده که ممکن است کد شما را هم بشکند. به همین سادگی، اما همین سه عدد، کل قرارداد اعتماد اکوسیستم متن‌باز است.

مثال واقعی ببینید: پکیجی از نسخهٔ 2.13.0 به 2.14.0 می‌رود؛ با خیال راحت به‌روزرسانی کنید چون فقط قابلیت اضافه شده. اما اگر به 3.0.0 رفت، قبل از به‌روزرسانی، مستندات بخش «تغییرات شکستنده» (Breaking Changes) را بخوانید، چون جایی در کد شما احتمالاً باید اصلاح شود. همین توانایی خواندن اعداد، شما را از کاربر تصادفیِ پکیج‌ها به کاربر آگاه تبدیل می‌کند.

نمادهای package.json را رمزگشایی کنید

فایل package.json نسخه‌ها را دقیق نمی‌نویسد؛ با نشانه‌هایی بازه تعیین می‌کند:

"dayjs": "^1.11.10",
"next": "~15.1.0",
"left-pad": "1.3.0"

• علامت ^ (کَرت): یعنی «نسخهٔ فرعی و اصلاحی جدید را بگیر، اما نسخهٔ اصلی را ثابت نگه دار»؛ ^1.11.10 تا 2.0.0 هر نسخه‌ای را می‌پذیرد.
• علامت ~ (تیلد): محدودتر است؛ فقط نسخه‌های اصلاحی را می‌گیرد؛ ~15.1.0 فقط تا 15.1.x می‌رود.
• نسخهٔ دقیق بدون نشانه: همان یک نسخه نصب می‌شود، نه چیزی دیگر؛ محافظه‌کارانه‌ترین حالت.
• علامت * یا latest: هر نسخه‌ای؛ در پروژهٔ جدی به‌معنای دعوت به آشوب است.

قاعدهٔ عملی: برای کتابخانه‌های معمولی از ^ استفاده کنید، برای پکیج‌های حساس به رفتار مثل ابزارهای بیلد، نسخهٔ دقیق یا ~ منطقی‌تر است. و یادتان باشد فایل قفل (lockfile) است که در عمل تصمیم نهایی نسخهٔ نصب‌شده را ثبت می‌کند.

وابستگی مستقیم، تو‌درتو و درخت پکیج

وابستگیِ مستقیم همان‌هایی است که خودتان نصب کرده‌اید؛ اما هر کدام، خودشان وابستگی دارند و آن‌ها هم وابستگی. نتیجه، درختی است که ممکن است صدها بستهٔ تو‌درتو (Transitive) داشته باشد. مشکل کلاسیک اینجاست: شما نسخهٔ ۲ از یک پکیج را می‌خواهید، یکی از وابستگی‌های تو‌درتو نسخهٔ ۱ را می‌خواهد و npm هر دو را کنار هم نصب می‌کند؛ حجم بیشتر، اما سازگاری حفظ می‌شود. با npm ls نام‌پکیج می‌توانید ببینید چه کسی و چرا آن نسخه را خواسته است.

درک همین درخت، کلید فهم «چرا با یک به‌روزرسانی کوچک همه‌چیز شکست؟» است: به‌روزرسانی یک پکیج فرعی، یکی از شاخه‌های عمیق درخت را عوض می‌کند و اگر جایی ناسازگاری وجود داشته باشد، خطا در جای غیرمنتظره ظاهر می‌شود. راه دفاع اول، lockfile است؛ راه دفاع دوم، به‌روزرسانی‌های کوچک و مکرر به‌جای به‌روزرسانی غول‌پیکرِ یک‌ساله است.

استراتژی به‌روزرسانی امن

• اصلاحی و فرعی را راحت بگیرید: با npm update به‌صورت ماهانه؛ ریسک کم و منفعت امنیتی زیاد.
• اصلی را آگاهانه بگیرید: هر ارتقای MAJOR را جداگانه، با خواندن راهنمای مهاجرت و در یک شاخهٔ جدا انجام دهید.
• تغییرات را بخوانید: فایل CHANGELOG هر پکیج، پنج دقیقه زمان می‌خواهد و ساعت‌ها دیباگ را حذف می‌کند؛ روش خواندن مستندات فنی عادت دقیقاً همین کار را می‌سازد.
• بعد از هر به‌روزرسانی، پروژه را اجرا و تست کنید: مسیرهای اصلی اپلیکیشن را یک دور دستی بچرخید.
• به‌روزرسانی وابستگی را در بازبینی کد جدی بگیرید: تغییرات وابستگی هم کد هستند؛ راهنمای بازبینی کد نگاه تیمی به همین تغییرات را قانونمند می‌کند.

یک عادت کوچک دیگر که این استراتژی را کامل می‌کند: هر ماه یک ساعت «بهداشت وابستگی» بگذارید؛ در آن یک ساعت، فهرست پکیج‌های قدیمی را ببینید، گزارش audit را مرور کنید و تصمیم بگیرید چه چیزی همین هفته به‌روزرسانی می‌شود. این جلسهٔ کوتاه، جلوی دو سناریوی بد را می‌گیرد: پروژه‌ای که هیچ‌وقت به‌روز نمی‌شود و امنیتش هر سال شکننده‌تر می‌شود، و پروژه‌ای که بعد از یک سال، به‌روزرسانی غول‌آسا می‌خورد که دیگر جرأت انجامش را ندارید. با جلسهٔ ماهانه، همیشه در ناحیهٔ امن حرکت می‌کنید.

SemVer در محصول خودتان

این قرارداد فقط برای نویسندگان کتابخانه نیست؛ هر جا کدی شما را «دیگری» استفاده می‌کند، SemVer معنا پیدا می‌کند. اگر یک API عمومی ساخته‌اید، تغییر شکستنده در پاسخ‌ها همان ارتقای MAJOR است و باید به کاربران API اطلاع برسد؛ راهنمای REST API برای مبتدیان مبنای این بحث است. اگر پکیج منتشر می‌کنید، هر انتشار را با تگ گیت مشخص کنید (git tag v1.4.0) تا تاریخ پروژه‌تان و نسخه‌ها یکی شوند؛ آموزش گیت و گیت‌هاب و راهنمای مشارکت در متن‌باز این چرخهٔ انتشار را کامل توضیح می‌دهند.

نسخه‌بندی معنایی در نگاه اول خشک و فنی به‌نظر می‌رسد، اما در عمل یکی از آن قواعد کوچکی است که دنیای نرم‌افزار متن‌باز را روی هم نگه می‌دارد. از امروز، سه عددِ کنار هر پکیج را نه به‌عنوان شماره، بلکه به‌عنوان پیام نویسنده به شما بخوانید؛ این تغییر نگاه، کیفیت تصمیم‌های وابستگی شما را برای همیشه بالا می‌برد.