रिलीज़-चक्र रनबुक

यह रनबुक apothem के vX.Y.Z रिलीज़ को एक स्वच्छ working tree से सत्यापित वितरण सतहों तक चलाता है। यह प्रक्रिया उस अनुरक्षक के लिए लिखी गई है जो gh, git, और रिलीज़-टियर शेल का उपयोग करता है; यह एक सत्यापित Release पेज, एक भरे हुए CHANGELOG, और एक इंस्टॉल-पथ स्मोक के साथ समाप्त होती है जो पुष्टि करता है कि प्रत्येक उपयोगकर्ता-सामना करने वाली सतह कैनोनिकल इंस्टॉल कमांड का उत्तर देती है।

रिलीज़ का आकार एकल-टैग, दो-चरण है। main पर एक हस्ताक्षरित रिलीज़ टैग .github/workflows/release.yml को ट्रिगर करता है, जो अपने पूर्ण आर्टिफ़ैक्ट सेट के साथ GitHub Release को बनाता, हस्ताक्षरित करता, अटेस्ट करता, और प्रकाशित करता है — sdist, wheel, CycloneDX SBOM, Sigstore cosign बंडल, SLSA-3 प्रोवेनेंस, और प्लेटफ़ॉर्म रनटाइम आर्काइव। वैकल्पिक दूसरा चरण publish-npm.yml का एक मैन्युअल डिस्पैच है, जो scripts/release/check-release-ready.sh के हरा होने के बाद @ahmed-g-gad/apothem को npmjs.com पर प्रकाशित करता है। संस्करण-युक्त CHANGELOG अनुभाग टैग कमिट के साथ लिखा जाता है; ऑपरेटर दोनों चरणों के उतरने के बाद इंस्टॉल-पथ स्मोक चलाता है।

1. पूर्वापेक्षाएँ

अनुरक्षक टैगिंग से पहले निम्नलिखित की पुष्टि करता है:

• Working tree. स्वच्छ (git status कुछ भी लंबित नहीं दिखाता)। रिलीज़ के लिए सभी फ़ीचर कार्य main पर है।

• CI हरा। नवीनतम main gh run list --branch=main --limit=1 --json conclusion --jq '.[0].conclusion' success लौटाता है।

• उपकरण। gh (GitHub CLI) संस्करण 2.40 या नवीनतर, ahmed-g-gad के विरुद्ध प्रमाणित; git 2.40 या नवीनतर जिसमें GPG हस्ताक्षर सबकी लोड हो; @ahmed-g-gad/apothem के लिए npm विश्वसनीय-प्रकाशक बंधन सक्रिय है (प्रकाशक-खाता-सेटअप रनबुक के अनुसार सत्यापित)।

• संस्करण एंकर संरेखित। pyproject.toml पर घोषित संस्करण स्ट्रिंग v उपसर्ग के बिना नियोजित टैग से मेल खाती है। सत्यापित करें:

  grep '^version' pyproject.toml

  अपेक्षित आउटपुट (vX.Y.Z रिलीज़ के लिए; प्लेसहोल्डर इन-फ़्लाइट रिलीज़ टैग का प्रतिनिधित्व करते हैं):

  version = "X.Y.Z"

• CHANGELOG अनुभाग तैयार। CHANGELOG.md में Keep-a-Changelog हेडिंग के अंतर्गत एक संस्करण-युक्त अनुभाग है। अनुरक्षक उसी कमिट में दिनांक और रिलीज़ बुलेट को अपडेट करता है जो टैग को उतारता है।

2. टैग और ट्रिगर

2.1 रिलीज़ कमिट लिखें

रिलीज़ कमिट दो परिवर्तन उतारता है:

• रिलीज़ की वास्तविक UTC दिनांक के साथ दिनांकित CHANGELOG.md संस्करण अनुभाग।
• pyproject.toml संस्करण नए संस्करण में उठाया गया (केवल तब जब main पर पूर्व कमिट पहले से पिछले-संस्करण पिन को धारण करता है और एक ताज़ा वृद्धि आवश्यक है; कमिट टैग समय से कुछ दिन पहले संस्करण-वृद्धि चक्र के दौरान भी उतर सकता है)।

उदाहरण कमिट:

git checkout main
git pull --ff-only origin main
# Author CHANGELOG and pyproject.toml edits via Edit tool, then:
git add CHANGELOG.md pyproject.toml
git commit -S -m "chore(release): cut vX.Y.Z"
git push origin main

-S फ़्लैग कमिट को GPG कुंजी से हस्ताक्षरित करता है। पुश मानक CI मैट्रिक्स (lint, test, build) को ट्रिगर करता है; टैगिंग से पहले हरे की प्रतीक्षा करें।

2.2 टैग पर हस्ताक्षर करें और पुश करें

git tag -a -s vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z

-a -s संयोजन एक एनोटेटेड, GPG-हस्ताक्षरित टैग बनाता है। पुश .github/workflows/release.yml को ट्रिगर करता है, जो बनाता, हस्ताक्षरित करता, अटेस्ट करता, और प्रकाशित करता है।

2.3 पुष्टि करें कि रिलीज़ वर्कफ़्लो पूर्ण हुआ

gh run watch $(gh run list --workflow=release.yml --limit=1 --json databaseId --jq '.[0].databaseId')

वर्कफ़्लो बिल्ड (sdist + wheel), SBOM जनरेशन (CycloneDX), कीलेस cosign हस्ताक्षरण, SLSA-3 प्रोवेनेंस जनरेशन और सत्यापन, प्लेटफ़ॉर्म आर्काइव बिल्ड (darwin / linux / windows), एक समेकित SHA256SUMS मैनिफ़ेस्ट के साथ आर्काइव हस्ताक्षरण, और अंतिम GitHub Release प्रकाशन चलाता है। अनुरक्षक एसेट-अपलोड पुष्टियों के लिए publish GitHub Release जॉब लॉग को स्कैन करता है।

2.4 npm प्रकाशन डिस्पैच करें (वैकल्पिक चरण)

GitHub Release और तैयारी गेट के हरा होने के बाद:

bash scripts/release/check-release-ready.sh vX.Y.Z
gh workflow run publish-npm.yml --field tag=vX.Y.Z

संकेत मिलने पर npmjs एनवायरनमेंट डिप्लॉयमेंट को स्वीकृत करें। वर्कफ़्लो npm Trusted Publishing (OIDC) के माध्यम से @ahmed-g-gad/[email protected] को npmjs.com पर प्रकाशित करता है; रिपॉज़िटरी में कोई रजिस्ट्री टोकन संग्रहीत नहीं है।

3. वितरण सतहें

प्रत्येक सतह के पास एक सत्यापन कमांड है जो "क्या रिलीज़ यहाँ उतरा?" का उत्तर देता है:

GitHub Release कैनोनिकल आर्टिफ़ैक्ट सतह है; npm पैकेज और स्क्रिप्ट इंस्टॉलर उसके ऊपर परत किए गए इंस्टॉल पथ हैं। npm प्रकाशन जानबूझकर अंतिम चरण है।

4. CHANGELOG अनुशासन

CHANGELOG.md Keep-a-Changelog परंपरा के अंतर्गत प्रति रिलीज़ एक अनुभाग रखता है। रिलीज़ कमिट का CHANGELOG संपादन:

• पुष्टि करता है कि संस्करण अनुभाग ## [X.Y.Z] — YYYY-MM-DD हेडिंग का उपयोग करता है।
• पुष्टि करता है कि मानक हेडिंग — Added, Changed, Deprecated, Removed, Fixed, Security — जहाँ लागू हो वहाँ उपयोग की जाती हैं। खाली हेडिंग रेंडर की गई फ़ाइल से हटा दी जाती हैं।
• क्षमताओं को कैप्चर करता है, कार्यान्वयन को नहीं। केवल डोमेन भाषा; कोई योजना-आंतरिक संदर्भ नहीं; कोई कमिट हैश नहीं; कोई योजना या फ़ेज़ पहचानकर्ता नहीं।

एक CHANGELOG अनुभाग जो अनुरक्षक की समीक्षा से बच गया, घोषणा कथन के लिए रिलीज़-नोट्स एंकर के रूप में पढ़ा जाता है।

5. इंस्टॉल-पथ स्मोक

दोनों चरण पूर्ण होने के बाद, अनुरक्षक स्मोक चलाता है। स्मोक वह कैनोनिकल सत्यापन है कि उपयोगकर्ता-सामना करने वाले इंस्टॉल कमांड उत्तर देते हैं।

5.1 Claude Code प्लगइन

/plugin marketplace add ahmed-g-gad/apothem
/plugin install apothem@apothem

अपेक्षित: प्लगइन इंस्टॉल होता है और apothem कमांड Claude Code के भीतर उपलब्ध हैं।

5.2 Node.js (npx)

npx @ahmed-g-gad/[email protected] --version

अपेक्षित आउटपुट: apothem X.Y.Z।

5.3 एक-शॉट स्क्रिप्ट इंस्टॉलर (POSIX)

curl -fsSL https://apothem.ahmedgad.com/install.sh | sh
apothem --version

अपेक्षित आउटपुट: apothem X.Y.Z।

5.4 एक-शॉट स्क्रिप्ट इंस्टॉलर (Windows)

irm https://apothem.ahmedgad.com/install.ps1 | iex
apothem --version

अपेक्षित आउटपुट: apothem X.Y.Z।

5.5 आर्टिफ़ैक्ट सत्यापन (आपूर्ति-श्रृंखला साक्ष्य)

gh release download vX.Y.Z --pattern 'apothem-X.Y.Z*' --pattern '*.cosign.bundle'
cosign verify-blob \
  --bundle apothem-X.Y.Z-py3-none-any.whl.cosign.bundle \
  --certificate-identity-regexp 'github.com/ahmed-g-gad/apothem' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  apothem-X.Y.Z-py3-none-any.whl
bash scripts/release/verify-provenance.sh vX.Y.Z

अपेक्षित: दोनों सत्यापन 0 के साथ बाहर निकलते हैं।

स्मोक प्रति सतह एक PASS / FAIL पंक्ति उत्पन्न करता है; पंक्तियों को अनुरक्षक के रिलीज़ लॉग में रिकॉर्ड करें।

6. विफलता पुनर्प्राप्ति

रिलीज़ वर्कफ़्लो में रिलीज़ इंजन और npm प्रकाशक के लिए प्रलेखित विफलता मोड हैं:

यदि एक पुनर्प्राप्ति चक्र एक नैदानिक पास के भीतर एक सतह को उतारने में विफल रहता है, तो सतह को रिलीज़ नोट्स में खुले इश्यू के लिंक के साथ एक ज्ञात-विफलता के रूप में लॉग किया जाता है; जब तक टूटी हुई सतह पैच रिलीज़ में ठीक की जा रही है, तब तक डाउनस्ट्रीम उपयोगकर्ताओं को काम करने वाली सतहों की ओर इंगित किया जाता है।

7. क्रॉस-रेफ़रेंस

• प्रकाशक सेटअप। प्रकाशक-खाता-सेटअप रनबुक npm विश्वसनीय-प्रकाशक बंधन और GitHub-पक्ष पूर्वापेक्षाएँ स्थापित करता है जिन्हें यह रनबुक मानता है।
• पुनर्प्राप्ति प्रवाह। रिलीज़-पुनर्प्राप्ति रनबुक (site/content/docs/runbooks/release-recovery.mdx) रिलीज़ कटओवर के दौरान क्रॉस-स्टेज विफलता पथ को नियंत्रित करता है, न कि §6 में नामित प्रति-सतह रिलीज़ विफलताओं को।
• Pages सक्षमीकरण। publish-static-site.yml वर्कफ़्लो प्रोजेक्ट वेबसाइट को कस्टम डोमेन पर सत्यापित और डिप्लॉय करता है; Pages-सक्षमीकरण रनबुक (site/content/docs/runbooks/pages-enablement.mdx) वह अपस्ट्रीम प्रक्रिया है जिसने सबसे पहले कस्टम डोमेन स्थापित किया।
• संस्करण नीति। site/content/docs/governance/release-engineering-policy.mdx SemVer + हस्ताक्षरण + अप्रचलन नीति रखता है जिसका यह रनबुक सम्मान करता है।