अर्थपूर्ण संस्करण 2.0.0

सारांश

एक संस्करण संख्या MAJOR.MINOR.PATCH को देखते हुए, वृद्धि:

  1. जब आप असंगत एपीआई परिवर्तन करते हैं तो प्रमुख संस्करण,
  2. MINOR संस्करण जब आप पिछड़े-संगत तरीके से कार्यक्षमता जोड़ते हैं, और
  3. जब आप पीछे-संगत बग फिक्स करते हैं तो पैच संस्करण।

प्री-रिलीज और मेटाडेटा के लिए अतिरिक्त लेबल MAJOR.MINOR.PATCH प्रारूप में एक्सटेंशन के रूप में उपलब्ध हैं।

परिचय

सॉफ्टवेयर प्रबंधन की दुनिया में “निर्भरता नरक” नामक एक डरावनी जगह मौजूद है। आपका सिस्टम बड़ा हो जाता है और जितना अधिक पैकेज आप अपने सॉफ़्टवेयर में एकीकृत करते हैं, उतना ही अधिक आप निराशा के इस गड्ढे में खुद को ढूंढने की संभावना रखते हैं।

कई निर्भरताओं वाले सिस्टम में, नए पैकेज संस्करण जारी करने से जल्दी ही एक दुःस्वप्न बन सकता है। यदि निर्भरता विनिर्देश बहुत तंग हैं, तो आप संस्करण लॉक (प्रत्येक आश्रित पैकेज के नए संस्करणों को जारी किए बिना पैकेज को अपग्रेड करने में असमर्थता) के खतरे में हैं। यदि निर्भरताओं को बहुत कम निर्दिष्ट किया गया है, तो आप अनिवार्य रूप से संस्करण संविधान द्वारा काट लेंगे (उचित से अधिक भविष्य के संस्करणों के साथ संगतता मानते हैं)। निर्भरता नरक वह जगह है जहां आप संस्करण लॉक और / या संस्करण संविधान आपको अपने प्रोजेक्ट को आगे और आसानी से स्थानांतरित करने से रोकते हैं।

इस समस्या के समाधान के रूप में, मैं नियमों और आवश्यकताओं का एक सरल सेट प्रस्तावित करता हूं जो निर्देश देते हैं कि संस्करण संख्याएं कैसे आवंटित की जाती हैं और वृद्धि हुई हैं। ये नियम बंद और खुले स्रोत सॉफ्टवेयर दोनों में उपयोग में पूर्व-मौजूदा व्यापक सामान्य प्रथाओं तक सीमित नहीं हैं, बल्कि यह आवश्यक नहीं हैं। इस प्रणाली के लिए काम करने के लिए, आपको सबसे पहले एक सार्वजनिक एपीआई घोषित करने की आवश्यकता है। इसमें दस्तावेज शामिल हो सकते हैं या कोड द्वारा ही लागू किया जा सकता है। भले ही, यह महत्वपूर्ण है कि यह एपीआई स्पष्ट और सटीक हो। एक बार जब आप अपनी सार्वजनिक एपीआई की पहचान कर लेंगे, तो आप अपने संस्करण संख्या में विशिष्ट वृद्धि के साथ इसमें परिवर्तनों को संवाद करेंगे। XYZ (Major.Minor.Patch) के संस्करण प्रारूप पर विचार करें। बग फिक्स एपीआई वृद्धि को प्रभावित नहीं करते हैं, पैच संस्करण, पिछड़ा संगत एपीआई जोड़ / परिवर्तन मामूली संस्करण में वृद्धि करता है, और पीछे की असंगत एपीआई परिवर्तन प्रमुख संस्करण में वृद्धि करता है।

मैं इस प्रणाली को “अर्थपूर्ण संस्करण” कहता हूं। इस योजना के तहत, संस्करण संख्याएं और जिस तरह से वे बदलते हैं, अंतर्निहित कोड के बारे में अर्थ बताते हैं और एक संस्करण से अगले संस्करण में क्या संशोधित किया गया है।

अर्थपूर्ण संस्करण विशिष्टता (सेमवीर)

मुख्य शब्द “जरूरी”, “आवश्यक नहीं”, “आवश्यक”, “साझा करें”, “नहीं होगा”, “चाहिए”, “नहीं होना चाहिए”, “अनुशंसित”, “मई” और “वैकल्पिक” इस दस्तावेज़ में हैं आरएफसी 2119 में वर्णित के रूप में व्याख्या किया जाना है ।

  1. अर्थपूर्ण संस्करण का उपयोग कर सॉफ्टवेयर एक सार्वजनिक एपीआई घोषित करना चाहिए। इस एपीआई को कोड में ही घोषित किया जा सकता है या दस्तावेज़ीकरण में सख्ती से मौजूद है। हालांकि यह किया जाता है, यह सटीक और व्यापक होना चाहिए।

  2. एक सामान्य संस्करण संख्या को XYZ फॉर्म लेना चाहिए जहां एक्स, वाई, और जेड गैर-ऋणात्मक पूर्णांक हैं, और इसमें प्रमुख शून्य शामिल नहीं होनी चाहिए। एक्स प्रमुख संस्करण है, वाई मामूली संस्करण है, और जेड पैच संस्करण है। प्रत्येक तत्व संख्यात्मक रूप से बढ़ना चाहिए। उदाहरण के लिए: 1.9.0 -> 1.10.0 -> 1.11.0।

  3. एक बार एक संस्करण पैकेज जारी किया गया है, उस संस्करण की सामग्री को संशोधित नहीं किया जाना चाहिए। किसी भी संशोधन को एक नए संस्करण के रूप में जारी किया जाना चाहिए।

  4. प्रमुख संस्करण शून्य (0.yz) प्रारंभिक विकास के लिए है। कुछ भी किसी भी समय बदल सकता है। सार्वजनिक एपीआई को स्थिर नहीं माना जाना चाहिए।

  5. संस्करण 1.0.0 सार्वजनिक एपीआई को परिभाषित करता है। इस रिलीज के बाद जिस संस्करण में संस्करण संख्या बढ़ी है, इस सार्वजनिक एपीआई पर निर्भर है और यह कैसे बदलता है।

  6. पैच संस्करण जेड (xyZ x> 0) केवल पिछड़ा संगत बग फिक्स पेश किए जाने पर वृद्धि की जानी चाहिए। एक बग फिक्स को आंतरिक परिवर्तन के रूप में परिभाषित किया जाता है जो गलत व्यवहार को हल करता है।
  7. छोटे संस्करण वाई (xYz x> 0) को बढ़ाया जाना चाहिए यदि सार्वजनिक, एपीआई के लिए नई, पिछली संगत कार्यक्षमता पेश की गई हो। यदि किसी भी सार्वजनिक एपीआई कार्यक्षमता को बहिष्कृत के रूप में चिह्नित किया गया है तो इसे बढ़ाया जाना चाहिए। निजी कोड के भीतर पर्याप्त नई कार्यक्षमता या सुधार पेश किए जाने पर यह बढ़ाई जा सकती है। इसमें पैच स्तर परिवर्तन शामिल हो सकते हैं। छोटे संस्करण को बढ़ाए जाने पर पैच संस्करण को 0 पर रीसेट किया जाना चाहिए।
  8. प्रमुख संस्करण एक्स (Xyz X> 0) को बढ़ाया जाना चाहिए यदि सार्वजनिक एपीआई में कोई पिछड़ा असंगत परिवर्तन पेश किया गया हो। इसमें मामूली और पैच स्तर परिवर्तन शामिल हो सकते हैं। जब बड़े संस्करण में वृद्धि हुई है तो पैच और मामूली संस्करण को 0 पर रीसेट किया जाना चाहिए।
  9. एक प्री-रिलीज संस्करण पैच संस्करण के तुरंत बाद एक हाइफ़न और डॉट अलग पहचानकर्ताओं की एक श्रृंखला को जोड़कर दर्शाया जा सकता है। पहचानकर्ताओं में केवल एएससीआईआई अल्फान्यूमेरिक्स और हाइफ़न [0-9 ए-ज़ा-जेड-] शामिल होना चाहिए। पहचानकर्ता खाली नहीं होना चाहिए। संख्यात्मक पहचानकर्ताओं में अग्रणी शून्य शामिल नहीं होना चाहिए। प्री-रिलीज संस्करणों में संबंधित सामान्य संस्करण की तुलना में कम प्राथमिकता है। एक प्री-रिलीज संस्करण इंगित करता है कि संस्करण अस्थिर है और इसके अनुरूप सामान्य संस्करण द्वारा बताए गए इच्छित संगतता आवश्यकताओं को पूरा नहीं कर सकता है। उदाहरण: 1.0.0-अल्फा, 1.0.0-अल्फा .1, 1.0.0-0.3.7, 1.0.0-x.7.z.92।

  10. पैच या प्री-रिलीज संस्करण के तुरंत बाद एक प्लस साइन और डॉट से अलग पहचानकर्ताओं की एक श्रृंखला को जोड़कर मेटाडाटा मई को इंगित किया जा सकता है। पहचानकर्ताओं में केवल एएससीआईआई अल्फान्यूमेरिक्स और हाइफ़न [0-9 ए-ज़ा-जेड-] शामिल होना चाहिए। पहचानकर्ता खाली नहीं होना चाहिए। संस्करण प्राथमिकता निर्धारित करते समय मेटाडेटा को अनदेखा किया जाना चाहिए। इस प्रकार दो संस्करण जो बिल्ड मेटाडेटा में भिन्न होते हैं, वही प्राथमिकता रखते हैं। उदाहरण: 1.0.0-अल्फा + 001, 1.0.0 + 20130313144700, 1.0.0-बीटा + exp.sha.5114f85।

  11. प्राथमिकता यह दर्शाती है कि आदेश दिए जाने पर संस्करणों की तुलना एक दूसरे से कैसे की जाती है। प्राथमिकता को उस क्रम में प्रमुख, मामूली, पैच और प्री-रिलीज पहचानकर्ताओं में संस्करण को अलग करके गणना की जानी चाहिए (मेटाडाटा बनाएं प्राथमिकता में नहीं है)। प्राथमिकता को पहले अंतर से निर्धारित किया जाता है जब इन पहचानकर्ताओं में से प्रत्येक को बाएं से दाएं से तुलना करें: मेजर, नाबालिग और पैच संस्करणों की तुलना हमेशा संख्यात्मक रूप से की जाती है। उदाहरण: 1.0.0 <2.0.0 <2.1.0 <2.1.1। जब प्रमुख, नाबालिग और पैच बराबर होते हैं, तो प्री-रिलीज़ संस्करण में सामान्य संस्करण की तुलना में कम प्राथमिकता होती है। उदाहरण: 1.0.0-अल्फा <1.0.0। एक ही प्रमुख, नाबालिग और पैच संस्करण के साथ दो प्री-रिलीज संस्करणों की प्राथमिकता प्रत्येक डॉट से अलग पहचानकर्ता को बाएं से दाएं की तुलना करके निर्धारित किया जाना चाहिए जब तक कोई अंतर निम्नानुसार नहीं मिलता है: केवल अंकों की पहचान करने वाले पहचानकर्ताओं की संख्या संख्यात्मक रूप से तुलना की जाती है और अक्षरों या हाइफ़न वाले पहचानकर्ताओं की तुलना एएससीआईआई क्रमबद्ध क्रम में तुलनात्मक रूप से की जाती है। गैर-संख्यात्मक पहचानकर्ताओं की तुलना में संख्यात्मक पहचानकर्ताओं की हमेशा कम प्राथमिकता होती है। प्री-रिलीज फ़ील्ड्स का एक बड़ा सेट एक छोटे से सेट की तुलना में अधिक प्राथमिकता है, यदि पिछले सभी पहचानकर्ता बराबर हैं। उदाहरण: 1.0.0-अल्फा <1.0.0-alpha.1 <1.0.0-alpha.beta <1.0.0-beta <1.0.0-beta.2 <1.0.0-beta.11 <1.0.0- आरसी .1 <1.0.0।

अर्थपूर्ण संस्करण का उपयोग क्यों करें?

यह एक नया या क्रांतिकारी विचार नहीं है। असल में, आप शायद पहले से ही कुछ करीब कर सकते हैं। समस्या यह है कि “करीबी” पर्याप्त नहीं है। औपचारिक विनिर्देश के किसी प्रकार के अनुपालन के बिना, निर्भरता प्रबंधन के लिए संस्करण संख्या अनिवार्य रूप से बेकार हैं। उपर्युक्त विचारों को नाम और स्पष्ट परिभाषा देकर, अपने इरादे को अपने सॉफ़्टवेयर के उपयोगकर्ताओं को संवाद करना आसान हो जाता है। एक बार इन इरादों को स्पष्ट, लचीला (लेकिन बहुत लचीला नहीं) निर्भरता विनिर्देशों को अंत में बनाया जा सकता है।

एक साधारण उदाहरण यह दिखाएगा कि कैसे अर्थपूर्ण संस्करणिंग निर्भरता नरक को अतीत की बात कर सकती है। “फायरट्रुक” नामक एक लाइब्रेरी पर विचार करें। इसे “सीढ़ी” नामक एक सेमेन्टिकली वर्जन पैकेज की आवश्यकता होती है। जब फायरट्रुक बनाया जाता है, तो लेडर संस्करण 3.1.0 पर होता है। चूंकि फायरट्रुक कुछ कार्यक्षमता का उपयोग करता है जिसे पहली बार 3.1.0 में पेश किया गया था, आप सुरक्षित रूप से लेडर निर्भरता को 3.1.0 से अधिक या बराबर के रूप में निर्दिष्ट कर सकते हैं लेकिन 4.0.0 से कम। अब, जब लेडर संस्करण 3.1.1 और 3.2.0 उपलब्ध हो जाते हैं, तो आप उन्हें अपने पैकेज प्रबंधन प्रणाली में छोड़ सकते हैं और जानते हैं कि वे मौजूदा आश्रित सॉफ्टवेयर के साथ संगत होंगे।

एक जिम्मेदार डेवलपर के रूप में, आप निश्चित रूप से सत्यापित करना चाहते हैं कि विज्ञापन के रूप में किसी भी पैकेज अपग्रेड का कार्य करें। वास्तविक दुनिया एक गन्दा जगह है; इसके बारे में हम कुछ नहीं कर सकते लेकिन सतर्क रहें। आप क्या कर सकते हैं अर्थपूर्ण संस्करण आपको निर्भर पैकेज के नए संस्करणों को रोल किए बिना संकुल को रिलीज़ और अपग्रेड करने के लिए एक मौका तरीका प्रदान करता है, जिससे आप समय और परेशानी बचा सकते हैं।

यदि यह सब वांछनीय लगता है, तो आपको अर्थपूर्ण संस्करण का उपयोग शुरू करने के लिए केवल इतना करना है कि आप ऐसा कर रहे हैं और फिर नियमों का पालन करें। इस वेबसाइट से अपने रीडमे से लिंक करें ताकि अन्य नियमों को जान सकें और उनसे लाभ उठा सकें।

सामान्य प्रश्न

0.yz प्रारंभिक विकास चरण में संशोधन के साथ मुझे कैसे निपटना चाहिए?

करने के लिए सबसे सरल बात यह है कि अपनी शुरुआती विकास रिलीज 0.1.0 पर शुरू करें और फिर प्रत्येक आगामी रिलीज के लिए मामूली संस्करण को बढ़ाएं।

मुझे कैसे पता चलेगा कि 1.0.0 कब रिलीज़ किया जाए?

यदि आपके सॉफ़्टवेयर का उत्पादन में उपयोग किया जा रहा है, तो यह शायद पहले से ही 1.0.0 होना चाहिए। यदि आपके पास स्थिर API है जिस पर उपयोगकर्ता निर्भर हैं, तो आपको 1.0.0 होना चाहिए। यदि आप पीछे की संगतता के बारे में बहुत कुछ चिंता कर रहे हैं, तो आपको शायद पहले ही 1.0.0 होना चाहिए।

क्या यह तेजी से विकास और तेजी से पुनरावृत्ति को हतोत्साहित नहीं करता है?

प्रमुख संस्करण शून्य तेजी से विकास के बारे में है। यदि आप हर दिन एपीआई बदल रहे हैं तो आपको अभी भी संस्करण 0.yz या अगले प्रमुख संस्करण पर काम कर रहे एक अलग विकास शाखा में होना चाहिए।

यदि सार्वजनिक एपीआई में सबसे छोटा पिछड़ा असंगत परिवर्तन भी एक प्रमुख संस्करण टक्कर की आवश्यकता है, तो क्या मैं संस्करण 42.0.0 पर बहुत तेजी से समाप्त नहीं होगा?

यह जिम्मेदार विकास और दूरदर्शिता का सवाल है। असंगत परिवर्तनों को हल्के ढंग से सॉफ़्टवेयर में पेश नहीं किया जाना चाहिए जिसमें बहुत से निर्भर कोड हैं। अपग्रेड करने के लिए जो लागत होनी चाहिए वह महत्वपूर्ण हो सकती है। असंगत परिवर्तनों को जारी करने के लिए प्रमुख संस्करणों को टक्कर देने का मतलब है कि आप अपने परिवर्तनों के प्रभाव के माध्यम से सोचेंगे, और शामिल लागत / लाभ अनुपात का मूल्यांकन करेंगे।

पूरे सार्वजनिक एपीआई को दस्तावेज करना बहुत अधिक काम है!

एक पेशेवर डेवलपर के रूप में यह आपकी ज़िम्मेदारी है कि दूसरों द्वारा उपयोग के लिए सॉफ्टवेयर का सही तरीके से दस्तावेज किया जाए। सॉफ़्टवेयर जटिलता का प्रबंधन करना एक परियोजना को कुशल रखने का एक बेहद महत्वपूर्ण हिस्सा है, और यदि कोई नहीं जानता कि आपके सॉफ़्टवेयर का उपयोग कैसे करें, या कॉल करने के लिए कौन सी विधियां सुरक्षित हैं, तो यह करना मुश्किल है। लंबे समय तक, सेमेन्टिक वर्जनिंग, और एक अच्छी तरह से परिभाषित सार्वजनिक एपीआई पर जोर हर किसी और सबकुछ सुचारू रूप से चल रहा है।

यदि मैं गलती से एक मामूली संस्करण के रूप में पिछड़ा असंगत परिवर्तन जारी करता हूं तो मैं क्या करूँ?

जैसे ही आप महसूस करते हैं कि आपने अर्थात् संस्करण संस्करण को तोड़ दिया है, समस्या को ठीक करें और एक नया मामूली संस्करण जारी करें जो समस्या को सुधारता है और पीछे की संगतता को पुनर्स्थापित करता है। इस परिस्थिति में भी, संस्करण संस्करणों को संशोधित करने के लिए अस्वीकार्य है। यदि यह उचित है, तो अपमानजनक संस्करण दस्तावेज करें और समस्या के अपने उपयोगकर्ताओं को सूचित करें ताकि वे अपमानजनक संस्करण से अवगत हों।

यदि मैं सार्वजनिक एपीआई को बदले बिना अपनी निर्भरता अपडेट करता हूं तो मुझे क्या करना चाहिए?

इसे संगत माना जाएगा क्योंकि यह सार्वजनिक एपीआई को प्रभावित नहीं करता है। सॉफ़्टवेयर जो स्पष्ट रूप से समान निर्भरताओं पर निर्भर करता है क्योंकि आपके पैकेज में अपनी निर्भरता विनिर्देश होनी चाहिए और लेखक को कोई भी विवाद दिखाई देगा। यह निर्धारित करना कि परिवर्तन एक पैच स्तर है या नाबालिग स्तर संशोधन इस बात पर निर्भर करता है कि आपने बग को ठीक करने या नई कार्यक्षमता को पेश करने के लिए अपनी निर्भरताओं को अपडेट किया है या नहीं। मैं आमतौर पर बाद के उदाहरण के लिए अतिरिक्त कोड की अपेक्षा करता हूं, इस मामले में यह स्पष्ट रूप से मामूली स्तर की वृद्धि है।

क्या होगा यदि मैं अनजाने में सार्वजनिक एपीआई को ऐसे तरीके से बदलता हूं जो संस्करण संख्या में परिवर्तन के अनुरूप नहीं है (यानी कोड पैच रिलीज में गलत ब्रेकिंग परिवर्तन को गलत तरीके से पेश करता है)?

अपने सबसे अच्छे फैसले का प्रयोग करें। यदि आपके पास एक विशाल दर्शक हैं जो सार्वजनिक एपीआई के इरादे से व्यवहार को बदलकर बहुत प्रभावित होंगे, तो यह एक प्रमुख संस्करण रिलीज करने के लिए सबसे अच्छा हो सकता है, भले ही फिक्स को पैच रिलीज माना जा सके। याद रखें, अर्थात् वर्जनिंग सब कुछ बताता है कि संस्करण संख्या कैसे बदलती है। यदि ये परिवर्तन आपके उपयोगकर्ताओं के लिए महत्वपूर्ण हैं, तो उन्हें सूचित करने के लिए संस्करण संख्या का उपयोग करें।

मुझे बहिष्करण कार्यक्षमता को कैसे संभालना चाहिए?

मौजूदा कार्यक्षमता को कम करना सॉफ्टवेयर विकास का एक सामान्य हिस्सा है और अक्सर प्रगति को आगे बढ़ाने की आवश्यकता होती है। जब आप अपने सार्वजनिक एपीआई का हिस्सा बहिष्कृत करते हैं, तो आपको दो चीजें करना चाहिए: (1) उपयोगकर्ताओं को परिवर्तन के बारे में जानकारी देने के लिए अपने दस्तावेज़ों को अपडेट करें, (2) जगह पर बहिष्करण के साथ एक नई मामूली रिलीज जारी करें। एक नई बड़ी रिलीज में कार्यक्षमता को पूरी तरह से हटाने से पहले कम से कम एक मामूली रिलीज होनी चाहिए जिसमें बहिष्करण शामिल है ताकि उपयोगकर्ता आसानी से नए एपीआई में संक्रमण कर सकें।

क्या वर्जन स्ट्रिंग पर सेमेवर की आकार सीमा है?

नहीं, लेकिन अच्छे फैसले का प्रयोग करें। उदाहरण के लिए, 255 वर्ण संस्करण स्ट्रिंग शायद अधिक है। साथ ही, विशिष्ट सिस्टम स्ट्रिंग के आकार पर अपनी सीमा लगा सकते हैं।

के बारे में

अर्थात् संस्करण संस्करण विनिर्देशन ट्रा प्रेस्टन-वर्नर , ग्रेवाटर के आविष्कारक और गिटहब के कोफाउंडर द्वारा लिखा गया है।

अगर आप फीडबैक छोड़ना चाहते हैं, तो कृपया गिटहब पर एक समस्या खोलें

लाइसेंस

क्रिएटिव कॉमन्स ― 3.0 द्वारा सीसी