בכל פעם שאנחנו מתקינים חבילה ב-npm, משדרגים ספרייה, או מפרסמים גרסה חדשה של הפרויקט שלנו - יש שם מספר שנראה בערך כך: 2.4.1. רוב המפתחים מכירים את המבנה הזה, אבל לא תמיד יודעים מה כל מספר אומר באמת.
האם לעלות מ-1.0.0 ל-1.0.1 זה אותו דבר כמו לעלות ל-1.1.0? ממש לא. יש פה שפה שלמה שנקראת Semantic Versioning - ובמאמר הזה נסביר אותה מהיסוד.
Semantic Versioning, או בקצרה semver, הוא סטנדרט פתוח לניהול גרסאות תוכנה שפורסם על ידי Tom Preston-Werner (אחד ממייסדי GitHub). הוא מגדיר בדיוק איך לבחור מספר גרסה - כך שכל מפתח בעולם יוכל להבין מייד מה השתנה בגרסה חדשה, מבלי לקרוא את ה-changelog.
הסטנדרט המלא זמין באתר הרשמי semver.org, ו-npm מאמצת אותו כחלק מרכזי בניהול חבילות - כפי שניתן לראות בתיעוד הרשמי של npm.
הרעיון הבסיסי: מספר גרסה צריך לספר סיפור. הוא לא רק "עוד מספר" - הוא הבטחה מהמפתח לכל מי שמשתמש בספרייה.
כל גרסה בנויה משלושה מספרים בפורמט X.Y.Z, כאשר כל אחד מהם מייצג רמה שונה של שינוי:
עולה כשמתקנים באג בצורה שלא שוברת שום דבר קיים. אם משתמשים בגרסה 2.4.1 וצריך לתקן באג קטן - הגרסה החדשה תהיה 2.4.2. הקוד של כל מי שמשתמש בספרייה ממשיך לעבוד בדיוק אותו דבר.
לפי המפרט של semver.org:
"PATCH version when you make backward compatible bug fixes."
עולה כשמוסיפים פונקציונליות חדשה שלא שוברת קוד קיים. אם הוספנו פיצ׳ר חדש לספרייה - המעבר יהיה מ-2.4.1 ל-2.5.0. שימו לב: ה-PATCH מתאפס חזרה לאפס.
לפי המפרט:
"MINOR version when you add functionality in a backward compatible manner."
המשמעות הפרקטית: כל מי שמשתמש בגרסה הישנה ממשיך לעבוד בלי שום שינוי. הם פשוט יכולים לבחור להשתמש בפיצ׳ר החדש - אם הם רוצים.
עולה כשמבצעים שינוי שעלול לשבור קוד קיים. זה מה שנקרא Breaking Change. אם שינינו את ה-API של פונקציה קיימת, הסרנו פרמטר, או שינינו את ה-return value - זה MAJOR.
המעבר יהיה מ-2.4.1 ל-3.0.0. גם ה-MINOR וגם ה-PATCH מתאפסים.
לפי המפרט:
"MAJOR version when you make incompatible API changes."
יש דרך קלה לזכור את שלושת הרמות:
כאשר MINOR עולה - ה-PATCH מתאפס. כאשר MAJOR עולה - גם MINOR וגם PATCH מתאפסים. כך תמיד נדע שגרסה 2.0.0 היא "נקודת פתיחה חדשה".
יש כלל נוסף שהרבה מפתחים לא מכירים: כשמספר ה-MAJOR הוא 0 (למשל 0.4.2), הספרייה נחשבת עדיין בשלב פיתוח ראשוני.
לפי semver.org:
"Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable."
במילים פשוטות: כשרואים גרסה שמתחילה ב-0, זה אומר שהכל עדיין יכול להשתנות ואין הבטחה לאחריות לאחור. הגרסה 1.0.0 היא זו שמכריזה רשמית: "הספרייה יציבה, ה-API מוגדר, אפשר לסמוך עלינו."
אם אתם עובדים עם Node.js, כנראה ראיתם קבצי package.json עם תלויות שנראות כך:
"dependencies": {
"react": "^18.2.0",
"lodash": "~4.17.21"
}הסימנים ^ ו-~ הם מה שנקרא version ranges - טווחי גרסאות. הם אומרים ל-npm אילו עדכונים מותר להתקין אוטומטית.
הסימן ^ לפני גרסה אומר: "תתקין את הגרסה הזו, ואפשר לעדכן אוטומטית כל עוד ה-MAJOR לא משתנה."
לדוגמה, ^18.2.0 יתקין כל גרסה בין 18.2.0 ל-19.0.0 (לא כולל). כלומר, עדכוני MINOR ו-PATCH יותקנו אוטומטית, אבל גרסה 19.x.x לא - כי היא עלולה לשבור קוד.
הסימן ~ שמרן יותר. הוא אומר: "תתקין רק עדכוני PATCH."
לדוגמה, ~4.17.21 יתקין כל גרסה בין 4.17.21 ל-4.18.0 (לא כולל). רק תיקוני באגים - ללא תוספות חדשות.
לפי תיעוד npm, הם ממליצים להתחיל חבילות חדשות מגרסה 1.0.0 ולדבוק בסטנדרט של semver על מנת שמשתמשי הספרייה יוכלו לנהל תלויות בצורה בטוחה.
יש כלל ברזל אחד בסמנטיק ורז'נינג שחשוב לדעת: גרסה שפורסמה היא קבועה לנצח.
לפי semver.org:
"Once a versioned package has been released, the contents of that version MUST NOT be modified."
אם גיליתם באג אחרי שפרסמתם 2.4.1 - אסור לשנות את 2.4.1. צריך לפרסם גרסה חדשה: 2.4.2. הסיבה פשוטה: אנשים שהתקינו 2.4.1 מצפים שהיא תישאר זהה. אם תשנו גרסה שכבר פורסמה, אתם שוברים את האמון של כל מי שמשתמש בספרייה שלכם.
Semantic Versioning הוא לא רק קונבנציה - הוא שפה משותפת שמאפשרת לאקוסיסטם שלם של ספריות וכלים לעבוד ביחד בצורה צפויה. כשכולם עומדים בסטנדרט, npm יכול להחליט אוטומטית אילו עדכונים בטוחים להתקין, ואתם יכולים לסמוך על כך שעדכון PATCH לא יפרק לכם את הפרויקט.
שלושת הכללים לזכור: