बैज नीति

यह दस्तावेज़ README बैज पट्टी और उसके गतिशील डेटा स्रोतों को प्रकाशित करने वाली अवसंरचना के लिए कैनोनिकल संदर्भ है। परियोजना के README का हर बैज यहाँ निर्दिष्ट तीन रूपों में से किसी एक के माध्यम से हल होता है; भविष्य में जोड़े जाने वाले नए बैज इन्हीं रूपों का पालन करते हैं, अन्यथा समीक्षा में अस्वीकार कर दिए जाते हैं।

1. पृष्ठभूमिCopy Anchor Link

स्थिर https://img.shields.io/badge/X-Y-Z URL अपने आप कभी नहीं बदलते, इसलिए वे परियोजना की वास्तविक स्थिति से भटक जाते हैं — एक release-vN-blue बैज vN+1 के शिप होने के बहुत बाद तक भी vN दिखाता रहता है। इसलिए नीति हर बदलने वाले मान के लिए गतिशील रूपों की माँग करती है, और स्थिर बैज को उन थोड़े-से मानों (लाइसेंस, Python लक्ष्य संस्करण) के लिए आरक्षित रखती है जो शायद ही कभी बदलते हैं, जहाँ स्थिर रूप ईमानदार होता है।

2. आर्किटेक्चरCopy Anchor Link

चार रूप परियोजना के हर बैज को कवर करते हैं:

1. GitHub-नेटिव वर्कफ़्लो स्थिति बैज। किसी वर्कफ़्लो के बैज URL का आकार https://github.com/<owner>/<repo>/actions/workflows/<file>/badge.svg होता है और यह डिफ़ॉल्ट ब्रांच पर नवीनतम रन को दर्शाता है। GitHub बैज को रिपॉज़िटरी के सार्वजनिक मेटाडेटा से परोसता है।
2. shields.io एंडपॉइंट बैज। एक shields.io एंडपॉइंट बैज एक https://img.shields.io/endpoint?url=<published-json> URL हल करता है, जहाँ JSON shields.io एंडपॉइंट स्कीमा (schemaVersion, label, message, color) के अनुरूप होता है। प्रकाशित JSON apothem.ahmedgad.com/badges/*.json पर रहता है; इसकी सामग्री हर सफल CI रन पर एक CI वर्कफ़्लो द्वारा उत्पन्न की जाती है। एंडपॉइंट बैज मेट्रिक्स को किसी तृतीय-पक्ष परिवर्तनशील स्टोर के बजाय परियोजना-नियंत्रित प्रकाशन के अंतर्गत रखते हैं।
3. shields.io स्थिर बैज। स्थिर बैज का आकार https://img.shields.io/badge/<label>-<message>-<color> होता है, जिसमें कोई प्रतिक्रियाशील डेटा स्रोत नहीं होता। यह उन मानों के लिए आरक्षित है जो वास्तव में शायद ही कभी बदलते हैं (लाइसेंस पहचानकर्ता, Python लक्ष्य संस्करण)।
4. रजिस्ट्री और स्कोरकार्ड बैज। ऐसा बैज जिसका मान कोई तृतीय पक्ष उस सार्वजनिक डेटा से गणना करता है जो उसके पास पहले से है: npm रजिस्ट्री (संस्करण और डाउनलोड, shields.io द्वारा रेंडर किए गए) और OpenSSF Scorecard API। परियोजना इनके लिए कुछ भी प्रकाशित नहीं करती; तृतीय पक्ष ही स्रोत है।

परियोजना मेट्रिक्स का सार्वजनिक-Gist प्रकाशन डिज़ाइन द्वारा बाहर रखा गया है। परियोजना-नियंत्रित डोमेन पर shields.io एंडपॉइंट इसका कैनोनिकल विकल्प हैं।

3. प्रति-बैज विनिर्देशCopy Anchor Link

तालिका README बैज पट्टी को क्रम से सूचीबद्ध करती है। अंतिम स्तंभ उन बैजों को चिह्नित करता है जिनकी छवि केवल तभी रेंडर होती है जब रिपॉज़िटरी सार्वजनिक हो: GitHub किसी निजी रिपॉज़िटरी का वर्कफ़्लो बैज केवल साइन-इन किए हुए सदस्यों को परोसता है, और Scorecard केवल सार्वजनिक रिपॉज़िटरी को स्कैन करता है।

github.com पर हर बैज का लिंक टारगेट (रिलीज़, वर्कफ़्लो, लाइसेंस फ़ाइल, इश्यू) केवल तभी खुलता है जब रिपॉज़िटरी सार्वजनिक हो।

badges वर्कफ़्लो भविष्य के बैजों के लिए coverage.json, security.json, supply-chain.json और docs.json एंडपॉइंट फ़ाइलें भी प्रकाशित करता है; README आज उन्हें नहीं दिखाता।

CodeQL एक समर्पित .github/workflows/codeql.yml वर्कफ़्लो के रूप में चलता है जो Python और Actions सतहों का विश्लेषण करता है; ci.yml में security-scan जॉब केवल bandit चलाता है, और CodeQL SARIF प्रकाशन codeql.yml पर छोड़ देता है। सुरक्षा बैज किसी GitHub-नेटिव वर्कफ़्लो बैज के बजाय badges वर्कफ़्लो द्वारा प्रकाशित एंडपॉइंट JSON का उपयोग करता है, जिससे बैज अंतर्निहित स्कैनर टोपोलॉजी बदलने पर भी स्थिर रहता है।

4. JSON प्रकाशन तंत्रCopy Anchor Link

एंडपॉइंट JSON .github/workflows/badges.yml द्वारा उत्पन्न किए जाते हैं। वर्कफ़्लो:

• ci वर्कफ़्लो पूरा होने के बाद workflow_run पर ट्रिगर होता है (और CI रन के बिना पुनः प्रकाशन के लिए मैनुअल workflow_dispatch पर भी)।
• नवीनतम रिलीज़ टैग को पूर्ण-इतिहास चेकआउट पर git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' से हल करता है (fetch-depth: 0; depth-1 चेकआउट पर कोई टैग किया गया कमिट पहुँच में नहीं होता और बैज unreleased दिखाता है), और पैरेंट CI निष्कर्ष को workflow_run इवेंट से।
• हर JSON को jq -n के माध्यम से उत्पन्न करता है, ताकि आउटपुट shields.io एंडपॉइंट स्कीमा (schemaVersion: 1, साथ ही label, message, color) से सख़्ती से मेल खाए।
• अपलोड से पहले हर उत्सर्जित JSON को jq -e से सत्यापित करता है।
• डायरेक्टरी को badges नामक वर्कफ़्लो आर्टिफ़ैक्ट के रूप में अपलोड करता है।

आर्टिफ़ैक्ट को apothem.ahmedgad.com/badges/ पर डिप्लॉय करने का काम .github/workflows/publish-static-site.yml संभालता है। साइट बिल्ड के दौरान वह वर्कफ़्लो नवीनतम सफल badges आर्टिफ़ैक्ट डाउनलोड करता है और उसे site/dist/badges/ के अंतर्गत स्टेज करता है। यदि आर्टिफ़ैक्ट अनुपस्थित है या उसकी अवधि समाप्त हो चुकी है, तो साइट फिर भी डिप्लॉय होती है और टूटा हुआ JSON प्रकाशित करने के बजाय लुप्त बैज आर्टिफ़ैक्ट को वर्कफ़्लो लॉग में दर्ज करती है।

5. रखरखाव प्रोटोकॉलCopy Anchor Link

नया बैज जोड़ते समय पहले रूप तय करें:

• यदि बैज किसी CI वर्कफ़्लो की रन-स्थिति दर्शाता है, तो GitHub-नेटिव रूप को प्राथमिकता दें। बैज का URL वर्कफ़्लो फ़ाइल से निर्धारित होता है; किसी प्रकाशन अवसंरचना की आवश्यकता नहीं होती।
• यदि बैज कोई ऐसा मेट्रिक (एक गणना, एक प्रतिशत, एक संस्करण स्ट्रिंग, एक श्रेणीबद्ध लेबल) दर्शाता है जो समय के साथ अपडेट होता है, तो shields.io एंडपॉइंट रूप का उपयोग करें। .github/workflows/badges.yml में मौजूदा पाँच चरणों के साथ एक JSON-उत्पादन चरण जोड़ें और apothem.ahmedgad.com/badges/<name>.json उपभोक्ता URL को README बैज पट्टी में जोड़ें।
• यदि बैज कोई ऐसा मान दर्शाता है जो वास्तव में शायद ही कभी बदलता है (लाइसेंस, भाषा लक्ष्य, शासन मोड), तो shields.io स्थिर रूप का उपयोग करें। बैज जोड़ते समय इस फ़ाइल की प्रति-बैज तालिका में परिवर्तन की आवृत्ति दर्ज करें।

किसी बैज को हटाने के लिए पहले उसे README से हटाएँ, फिर badges वर्कफ़्लो से उसका JSON-उत्पादन चरण हटाएँ, फिर ऊपर की प्रति-बैज तालिका से उसकी पंक्ति हटाएँ। हटाने को एक परमाणु बदलाव रखें, ताकि README कभी ऐसे JSON आर्टिफ़ैक्ट का संदर्भ न दे जिसे वर्कफ़्लो उत्पन्न नहीं करता।

6. पारस्परिक संदर्भCopy Anchor Link

• वह CI वर्कफ़्लो जिसकी रन-स्थिति GitHub-नेटिव CI बैज दर्शाता है: .github/workflows/ci.yml।
• वह badges वर्कफ़्लो जो एंडपॉइंट JSON प्रकाशित करता है: .github/workflows/badges.yml।
• वह स्थिर-साइट डोमेन जो JSON परोसता है: apothem.ahmedgad.com।
• shields.io एंडपॉइंट स्कीमा संदर्भ: https://shields.io/badges/endpoint-badge।