सिमेंटिक वर्शनिंग

सिमेंटिक वर्शनिंग (SemVer) - संस्करण संख्या परिवर्तनों की प्रकृति को कैसे दर्शाती है, इस पर एक अनुबंध। प्रारूप: मेजर। माइनर। PATCH [-PRERELEESE] [+ BUILD]।

• मेजर - असंगत परिवर्तन (ब्रेकिंग)।
• MINTER - पारस्परिक रूप से संगत विशेषताएं/एक्सटेंशन।
• PATCH - बैकवर्ड संगत बग/सुरक्षा फिक्स।

लक्ष्य: एपीआई, घटनाओं, डेटा स्कीमा, एसडीके और अचानक उपभोक्ता टूटने के बिना कॉन्फ्रेंस का अनुमानित विकास।

1) कन्वेंशन नंबर

X.Y.Z[-alpha.1    -rc.1][+build.sha]

प्री-रिलीज़ ('-alpha', '-beta', '-rc') - अस्थिर विधानसभाएँ; संगतता का वादा मत करो।

बिल्ड मेटाडेटा ('+ sha') - तुलना क्रम को प्रभावित नहीं करता है, जो ट्रेसिंग के लिए उपयोगी है।

1 तक। 0. 0 किसी भी बदलाव को तोड़ ने पर विचार किया जा सकता है (लेकिन शुरू से ही नियमों का पालन करना बेहतर है)।

2) क्या तोड़ ने/मामूली/पैच पर विचार करें

• अनुबंध को बदले बिना कीड़े और सुरक्षा के लिए निर्धारण।
• डॉकिंग अपडेट जो संविदा को प्रभावित नहीं करते हैं।
• प्रतिक्रियाओं/घटनाओं/योजनाओं को बदले बिना अनुकूलन।

• नया वैकल्पिक क्षेत्र/विधियाँ/समापन बिंदु जोड़ें।
• यदि उपभोक्ता अपरिचित मूल्यों को सहन करते हैं तो मूल्यों का विस्तार करना।
• नए डेटाबेस सूचकांक, डिफ़ॉल्ट के साथ शून्य स्तंभ, पुराने के अलावा नई घटनाएँ।

• फ़ील्ड मिटाना/नाम बदलना, प्रकार बदलना, अनिवार्य।
• शब्दार्थ/स्टेटस/त्रुटि कोड बदलें।
• क्रमबद्धता प्रारूप, कुंजी योजना, परिवहन प्रोटोकॉल बदलना।
• विषयों को संपीड़ित/मर्ज करें, घटना का अर्थ स्थानांतरित करें, विभाजन योजना को बदल दें।
• डेटाबेस माइग्रेशन जिन्हें पिछड़े संगतता के बिना "दो-चरण" स्विच करने की आवश्यकता होती है।

3) आर्टिफ़ैक्ट वर्शनिंग

3. 1 REST

वेरिएंट: 'URI/v1/...', शीर्षिका ('स्वीकार करें: अनुप्रयोग/vnd. acme। खेल + json; संस्करण = 1 '), पैरामीटर।

सिफारिश: सार्वजनिक एपीआई के लिए यूआरआई में संस्करण; आंतरिक के लिए - हेडर c बातचीत के माध्यम से।

माइनर: वैकल्पिक क्षेत्र, नए फिल्टर/संसाधन जोड़ें; मौजूदा उत्तर न बदलें।

PATCH: सुधार, परिभाषा शोधन, स्थिर छंटाई।

3. 2 जीआरपीसी

मेजर → हस्ताक्षर/प्रकार बदलना (नया पैकेज/सेवा: 'acme। बटुआ। v2 ')।

नए क्षेत्र - लेबल वैकल्पिक; सर्वर को अज्ञात को अनदेखा करना होगा।

हम खेतों को हटाते नहीं हैं: "डिप्रिकेट + एक संख्या आरक्षित करें", हटाएं - केवल अगले मेजर में।

3. 3 ग्राफ़क्यूएल

माइनर: नए क्षेत्र/प्रकार/क्वेरी; निष्कासन - '@ deprecated' + माइग्रेशन विंडो के माध्यम से, पूर्ण निष्कासन - MAJ

बदलें nullable→non -nullable - MAJER।

3. 4 घटनाएँ और विषय (काफ्का/एसक्यूएस)

स्कीमा रजिस्ट्री में स्कीमा: एडिटिव का विकास (डिफ़ॉल्ट के साथ फ़ील्ड जोड़ें)।

नया असंगत संस्करण → नया विषय/विषय ('बेट। सेटलमेंट। v2 ')।

विभाजन कुंजी मेजर के भीतर अपरिवर्तनीय है।

3. 5 डीबी आरेख

1. एक स्तंभ जोड़ें (nullable/default) →

2. बैकफिल में भरें →

3. → पढ़ें अनुवाद करें

4. पुराना (केवल मेजर) हटाएँ।

परिवर्तन प्रकार/पीके/विशिष्टता - मेजर, फिचफ्लाग और डबल प्रविष्टि के तहत।

3. 6 एसडीके/सीएलआई

सार्वजनिक तरीके/हस्ताक्षर समान नियम हैं।

ऑटोजेनरेशन (OpenAPI/Proto) के लिए - बैच नाम और कलाकृतियों का संस्करण।

4) अभाव नीति और जीवन चक्र

प्रत्येक ब्रेकिंग परिवर्तन अवक्षेपण से पहले होता है (आमतौर पर बाहरी के लिए 90-180 दिन, आंतरिक के लिए 30-60)।

संचार: चेंजलॉग, ई-मेल/वेबहूक टू पार्टनर, डेवलपर पोर्टल में बैनर।

दोहरे रन मोड: समानांतर में 'v1' और 'v2' रखें, ट्रैफिक 'v1' के हिस्से की निगरानी करें।

सनसेट हेडर (REST): 'सनसेट: 2026-03-31', 'लिंक: ; rel = "deprecation" '।

5) संस्करण वार्ता

क्लाइंट वांछित संस्करण + अधिकतम समर्थित संस्करण भेजता है (उदाहरण के लिए, 'स्वीकार करें-संस्करण: 1,2')।

सर्वर 'कंटेंट-वर्जन के साथ जवाब देता है: 2' if यह बढ़ावा दे सकता है।

द्विदिश प्रोटोकॉल (WebSocket, gRPC) में - 'समर्थित _ संस्करण' के साथ हैलो फ्रेम का आदान-प्रदान।

6) प्रदाता एडाप्टर एकीकरण (एसीएल)

बाहरी प्रदाता योजना को बदल देता है - एडाप्टर के अंदर हम v1/v2 मैपर रखते हैं और अपने डोमेन अनुबंध को बनाए रखते हुए आंतरिक घटना के लिए MINTER जारी करते हैं।

यदि बाहरी परिवर्तन अपने तरीके से अंदर आते हैं, तो यह हमारे डोमेन इवेंट का मेजर और एक नया विषय है।

7) चेंजेलॉग और कमिट लेबल

• 'फेट:...' → MINTER
• 'फिक्स:... '/' कोर ',' डॉक्स ',' पर्फ '(कोई अनुबंध नहीं) → PATCH
• 'फेट!: '/' फिक्स!: '/' रिफैक्टर!:' या 'ब्रेकिंग चेंज:' इन मेजर - बॉडी

[2.3.0] - 2025-10-31
Added
- GET /v1/games?capabilities=jackpot (optional)
Changed
- GraphQL: field Game.volatility @deprecated, use Game.riskProfile

8) रिलीज़ ऑटोमेशन

CI: सर्किट वेलिडेटर (OpenAPI/Protobuf/Avro/JSON-Schema), ब्रेकिंग-डिफ्यूज़पता लगाएं। अधिक

SemVer-bot: विश्लेषण पारंपरिक कमिट्स - टक्कर (प्रमुख/मामूली/पैच) की गणना करता है, एक टैग डालता है, एक चेंजलॉग उत्पन्न करता है।

सीडी: अलग तैनाती और रिलीज (phicheflags/configs नए संस्करण को सक्रिय करते हैं)।

नियंत्रण: सफल कैनरी और सहमत एसएलओ तक पीआरओ पर 'नवीनतम' प्रकाशित न करें।

9) विन्यास और नीतियों के लिए शब्दार्थ

कॉन्फ़िग्स (YAML/JSON) का एक स्कीमा संस्करण भी है: 'स्कीमा _ संस्करण: 3'।

माइनर - नए वैकल्पिक क्षेत्र/नियम मेजर - संरचना/दायित्व का परिवर्तन।

v2/v3 सत्यापन में समर्थन; असंगति रिपोर्ट के साथ कॉन्फिग प्रवासी।

10) संगतता परीक्षण

उपभोक्ता-संचालित अनुबंध परीक्षण (संधि): प्रति एकीकरण।

स्कीमा-इवोल्यूशन परीक्षण: एक नए स्कीमा पर पुराने पेलोड चलाएं और इसके विपरीत।

रीप्ले - छाया में उत्पादन यातायात 'v1' से 'v2' तक खेलता है।

संपत्ति-आधारित: अपरिचित क्षेत्रों/एनम के लिए प्रतिरोध।

11) संस्करण द्वारा अवलोकन

टैग मेट्रिक्स/लॉग: 'api _ version', 'schema _ version', 'event _ version'.

प्रवासन डैशबोर्ड: संस्करणों द्वारा ट्रैफिक शेयर, 'v1/v2' द्वारा त्रुटि/विलंबता।

अलर्ट: यदि 'v1' योजना के अनुसार नीचे नहीं जाता है; 4xx/5xx वृद्धि 'v2' रिलीज के बाद।

12) डाउनटाइम के बिना प्रवासन पैटर्न

विस्तार → माइग्रेट → अनुबंध (БД)।

रीडिंग स्विच करने से पहले डुअल राइट + डायवर्जेंस की तुलना करें।

छाया रैंकिंग/नियमों के लिए तुलना करें।

किरायेदार/क्षेत्र द्वारा कैनरी; त्वरित रोलबैक के लिए झंडे की सुविधा।

रीड-कॉम्पैट/राइट-कॉम्पैट विंडो: नया संस्करण पुराने डेटा को पढ़ ता है, लेकिन एक नए प्रारूप में लिखता है।

13) एंटी-पैटर्न

संसाधन/घटना को वर्शन करने के बजाय "प्रत्येक क्षेत्र में संस्करण"।

माइनर के तहत छिपे हुए ब्रेकिंग परिवर्तन (उदाहरण के लिए, डिफ़ॉल्ट बदलना)।

खिड़की और खपत मैट्रिक्स के बिना चित्रित हटाना।

"फॉरएवर वी 1": → तकनीकी ऋणों और कमजोरियों के पुराने संस्करणों को हटाने की कोई योजना नहीं है।

व्यवसाय संस्करण और कंटेनर छवि संस्करण मिलाएं।

14) वर्शनिंग पॉलिसी चेकलिस्ट

• निश्चित संस्करण प्रारूप और सत्य के स्रोत (रजिस्ट्री/पोर्टल)।
• कलाकृतियों (REST/gRPC/GraphQL/events/DB) द्वारा ब्रेकिंग मानदंडों की अनुमोदित सूची।
• अवक्षेपण प्रक्रिया: समय, संचार, सूर्यास्त/बैनर, दोहरे रन।
• स्वचालित डिफ चेकर और पारंपरिक कमिट।
• संस्करण और सतर्क खपत डैशबोर्ड।
• प्रवासन प्लेबुक (विस्तार/माइग्रेट/अनुबंध, दोहरे-लेखन, छाया)।
• कॉन्फ़िग और एसडीके के अपने संस्करण और केस हैं।
• प्रलेखन "ग्राहकों के लिए एक संस्करण कैसे चुनें" और टीमों के लिए "कैसे अपग्रेड करें"।

15) संस्करण के उदाहरण (आईगेमिंग मामले)

'BetSuted v1' event → 'v2': 'void _ couse' (वैकल्पिक) और 'टैक्स' जोड़ा गया। राशि '(वैकल्पिक) - माइनर। नाम बदलकर 'payout'→'win_amount' - मेजर, एक नया विषय।

REST '/वॉलेट/ट्रांसफर ': जोड़ा फ़िल्टर'? किरायेदार _ id = '- MINTER। परिवर्तित त्रुटि कोड '409'→'422' - मेजर।

ग्राफक्यूएल: चिह्नित 'प्लेयर। 'खिलाड़ी' के पक्ष में '@ deprecated' के रूप में आयु। EgGroup '- MINTER में रिलीज़, मेजर में अवधि के बाद विलोपन

DB: जोड़ा गया स्तंभ 'bonus _ wager _ befe' nullable - MINTER। गैर-शून्य और विलोपित 'बोनस _ बाएं' - मेजर (विस्तार/अनुबंध के माध्यम से)।

निष्कर्ष

शब्दार्थ संस्करण संख्याओं के बारे में नहीं है, बल्कि विश्वास और पूर्वानुमेयता के बारे में है। स्पष्ट नियम, स्वचालित जाँच, नियंत्रित चित्रण, और पारदर्शी टेलीमेट्री एपीआई, घटनाओं और दर्द-मुक्त स्कीमा को एकीकरण के लिए विकसित करने की अनुमति देते हैं - और अक्सर, सुरक्षित और सार्थक रूप से परिवर्ण करते हैं।