SemVer पार्सर और तुलनाकारी

सिमेंटिक संस्करण पार्सर क्या है?#

Semantic Versioning (SemVer) वह major.minor.patch परिपाटी है जो अधिकांश लाइब्रेरी यह संकेत करने के लिए उपयोग करती हैं कि किसी रिलीज़ में किस प्रकार का परिवर्तन है: कोई बग सुधार patch बढ़ाता है, पिछले-संस्करण-संगत जोड़ minor बढ़ाते हैं, और breaking परिवर्तन major बढ़ाते हैं। कोई pre-release टैग (1.0.0-beta.1) या build मेटाडेटा (+exp.sha.1) जोड़ें और आपको semver.org 2.0.0 पर परिभाषित पूर्ण व्याकरण मिलती है।

मुश्किल यह है कि “दो संस्करण तुलना करें” और “क्या यह संस्करण मेरी dependency श्रेणी को संतुष्ट करता है” आँख से गलत करना आसान है। क्या 1.0.0 1.0.0-beta से ऊँचा या निचला है? (ऊँचा — एक रिलीज़ हमेशा अपने pre-release से श्रेष्ठ होती है।) क्या 1.2.3, ^1.2.0 को संतुष्ट करता है? (हाँ।) क्या यह ~1.2.0 को संतुष्ट करता है? (भी हाँ, किंतु एक कस कारण से।) यह पेज संस्करणों को वैसे पार्स करता है जैसे स्पेक परिभाषित करता है, आपको घटक दिखाता है, दो संस्करणों की precedence द्वारा तुलना करता है, और उसी ^ / ~ / >= / || / hyphen सिंटैक्स के साथ श्रेणी क्वेरी का उत्तर देता है जो किसी 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 किए गए समूह, जैसे वास्तविक dependency श्रेणियाँ लिखी जाती हैं। समर्थित सिंटैक्स: ^ (caret), ~ (tilde), >= <= > < =, x / X / * wildcards, आंशिक संस्करण (1.2), - hyphen श्रेणियाँ, और समूहों को OR करने के लिए ||।
4. दो पार्स कार्ड पढ़ें। प्रत्येक canonical clean रूप और अलग-अलग major, minor, patch, prerelease, और build फ़ील्ड दिखाता है। कोई अमान्य संस्करण अपना कार्ड एक संदेश के साथ लाल कर देता है।
5. तुलना कार्ड पढ़ें। यह precedence द्वारा A < B, A = B, या A > B बिछाता है, साथ ही diff — सबसे ऊँचा घटक जो बदला (major, minor, patch, prerelease, या build)।
6. श्रेणी जाँच कार्ड पढ़ें। यह आपके द्वारा टाइप की गई श्रेणी के लिए बताता है कि क्या A इसे संतुष्ट करता है और क्या B।

मुख्य विशेषताएँ#

• स्पेक के अनुसार precedence। तुलना major.minor.patch पर और फिर pre-release पहचानकर्ताओं पर चलती है, इस नियम के साथ कि बिना pre-release वाला संस्करण हमेशा पूर्व वाले से श्रेष्ठ होता है। संख्यात्मक पहचानकर्ता संख्यात्मक रूप से तुलना होते हैं (beta.2 < beta.11); अक्षरांकीय व्युत्क्रम में तुलना होते हैं; और संख्यात्मक हमेशा अक्षरांकीय से नीचे रैंक करता है। Build मेटाडेटा पार्स और प्रदर्शित होता है किंतु कभी precedence को प्रभावित नहीं करता।
• Caret और tilde, सही ढंग से desugar। ^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 का “leftmost non-zero” नियम। Tilde उसी minor पर pin करता है: ~1.2.3 का अर्थ >=1.2.3 <1.3.0।
• ||, hyphens, और wildcards के साथ श्रेणियाँ। ^1.0.0 || >=2.0.0 <3.0.0 (दो समूहों का OR), 1.2.0 - 1.5.0 (समावेशी hyphen श्रेणी), 1.x / 1.2.* (wildcard श्रेणियाँ) सभी पार्स और परीक्षित होते हैं।
• pre-release समावेशन गेट। एक pre-release संस्करण किसी श्रेणी को तभी संतुष्ट कर सकता है जब उसी समूह में कोई comparator उसी major.minor.patch पर pre-release टैग लेकर जाता हो। इसलिए 1.5.0-rc.1, ^1.2.0 को संतुष्ट नहीं करता, किंतु यह ^1.5.0-rc.0 को संतुष्ट करता है — वैसे ही जैसे वास्तविक पैकेज मैनेजर आपके रिलीज़ बिल्ड से यादृच्छिक pre-releases को बाहर रखते हैं।
• कहानी बताने वाला diff। diff फ़ील्ड सबसे ऊँचा बदला गया घटक रिपोर्ट करता है, इसलिए 1.2.3 से 2.0.0 पर जाने पर major दिखता है, और 1.0.0 से बदले हुए build के साथ 1.0.0 पर build दिखता है यद्यपि precedence अपरिवर्तित।
• क्षमाशील इनपुट। अग्रणी v, अग्रणी =, और चारों ओर रिक्ति सहन की जाती है, इसलिए किसी git tag या changelog से कॉपी किए गए संस्करण हाथ से सफ़ाई किए बिना पार्स होते हैं।

विस्तृत उदाहरण#

डिफ़ॉल्ट के साथ — 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 में बदलें और इसका बैज संतुष्ट नहीं करता पर पलट जाता है — ऊपरी सीमा <3.0.0 इसे बाहर रखती है।

pre-release नियम को क्रिया में देखने के लिए, A को 1.5.0-rc.1 और B को 1.5.0 पर सेट करें, और श्रेणी को ^1.5.0-rc.0 रखें। अब A संतुष्ट करता है (वही 1.5.0, श्रेणी में मैचिंग pre-release टैग है), जबकि एक सादा ^1.5.0 1.5.0-rc.1 को नहीं जाने देता — यह गेट ठीक release candidates को release dependency समाधान से तब तक बाहर रखने के लिए मौजूद है जब तक आप opt in न करें।

अक्सर पूछे जाने वाले प्रश्न#

क्या 1.0.0, 1.0.0-beta से ऊँचा है?#

हाँ। बिना pre-release टैग वाला संस्करण हमेशा उससे ऊँची precedence रखता है जिसमें pre-release टैग है, यहाँ तक कि उसी major.minor.patch पर भी। इसलिए 1.0.0 > 1.0.0-rc.1 > 1.0.0-beta.11 > 1.0.0-alpha। यही कारण है कि किसी रिलीज़ का “gold होना” एक वास्तविक precedence वृद्धि है, केवल एक लेबल परिवर्तन नहीं।

^ और ~ में क्या अंतर है?#

caret वे अद्यतन अनुमति देता है जो left-most non-zero घटक को संशोधित नहीं करते: ^1.2.3 कोई भी 1.x.x 1.2.3 से (लेकिन 2.0.0 को छोड़कर) तक अनुमति देता है। tilde सख़्त है — पूर्ण संस्करण दिए जाने पर यह minor को pin करता है: ~1.2.3 केवल 1.2.x अनुमति देता है। केवल major दिए जाने पर (~1), tilde और caret दोनों पूरा major श्रेणी अनुमति देते हैं। अधिकांश लाइब्रेरी ^ से pin करती हैं; अपने स्वयं प्रकाशित पैकेजों के patches अक्सर ~ उपयोग करते हैं।

मेरा pre-release संस्करण ^1.0.0 को क्यों नहीं संतुष्ट करता?#

डिज़ाइन से। 1.5.0-rc.1 जैसा pre-release किसी श्रेणी को तभी संतुष्ट करता है जब उसी AND-समूह में कोई comparator उसी 1.5.0 पर pre-release टैग रखता हो। ^1.0.0, >=1.0.0 <2.0.0-0 में desugar होता है 1.5.0 पर कोई pre-release के बिना, इसलिए गेट आपके रिलीज़ बिल्ड को किसी के यादृच्छिक release candidate को खींचने से रोकता है। यदि आप opt in करना चाहते हैं, तो ^1.5.0-rc.0 स्पष्ट रूप से लिखें।

क्या build मेटाडेटा तुलना को प्रभावित करता है?#

नहीं। 1.0.0+exp.sha.5 और 1.0.0+exp.sha.6 की समान precedence है — build मेटाडेटा केवल पहचान के लिए है। पार्सर इसे अभी भी दिखाता है (और जब केवल मेटाडेटा भिन्न हो diff एक build परिवर्तन रिपोर्ट करता है), किंतु यह कभी क्रम तय नहीं करता।