डिपेंडेंसी पिनिंग मैनिफ़ेस्ट
डिपेंडेंसी घोषणा नीति, जो Python रनटाइम रेंज, डेवलपमेंट टूलिंग, रिलीज़-टूल लॉक फ़ाइलों, और प्रत्येक बिल्ड सतह के लिए अनुमोदित संस्करण निचली सीमाओं को कवर करती है।
Apothem डिपेंडेंसी को कैसे घोषित, पिन, और लॉक करता है, इसके लिए अनुमोदित रुख। श्रोता: योगदानकर्ता और डाउनस्ट्रीम उपभोक्ता जिन्हें पुनरुत्पादनीयता मॉडल समझने की आवश्यकता है।
रुख
Apothem एक Python CLI है जिसमें रनटाइम डिपेंडेंसी का एक छोटा सेट है, साथ ही एक
बड़ी डेवलपमेंट, ऑडिट, रिलीज़, और दस्तावेज़ टूलचेन है। रनटाइम डिपेंडेंसी
pyproject.toml में रूढ़िवादी निचली सीमाओं का उपयोग करती हैं; वेबसाइट
site/package-lock.json को कमिट करती है; GitHub Actions संस्करण टिप्पणियों के साथ
अपरिवर्तनीय SHA द्वारा पिन की जाती हैं और Renovate द्वारा अपग्रेड की जाती हैं।
| श्रेणी | घोषणा | लॉक नीति |
|---|---|---|
| रनटाइम Python डिपेंडेंसी | pyproject.toml में [project.dependencies] | निचली-सीमा रेंज; कोई कमिट की गई Python रनटाइम लॉक नहीं |
| डेवलपमेंट / सुरक्षा टूलिंग | [project.optional-dependencies] extras | निचली-सीमा रेंज; CI वर्तमान मेल खाते संस्करण इंस्टॉल करता है |
| रिलीज़ टूलिंग | scripts/release/requirements-build-linux.txt | रिलीज़ वर्कफ़्लो के लिए हैश-लॉक; रिलीज़ टूलिंग क्लोज़र से जनरेट किया गया |
| केवल-CI टूल | .github/workflows/*.yml | केवल वर्कफ़्लो वाले pip टूल सटीक पिन उपयोग करते हैं (pip, bandit, pip-audit, pip-licenses, pyinstaller) |
| दस्तावेज़ साइट | site/package.json | site/package-lock.json कमिट किया गया और npm ci द्वारा उपभोग किया गया |
| GitHub Actions | संस्करण टिप्पणियों के साथ SHA-पिन की गई uses: रेफ़रेंस | Renovate अपडेट प्रस्तावित करता है; अपवाद action-pinning-exempt: मार्कर रखते हैं |
रिलीज़ अनुमोदन
| सतह | अनुमोदित स्थिति | औचित्य |
|---|---|---|
| रनटाइम डिपेंडेंसी | वर्तमान निचली सीमाएँ pyproject.toml [project.dependencies] में रहती हैं | रिलीज़ से पहले अनुमोदित वर्तमान स्थिर निचली सीमाएँ; कोई ज्ञात रनटाइम CVE अवरोधक नहीं |
| डेवलपमेंट टूलिंग | वर्तमान निचली सीमाएँ pyproject.toml के dev extra में रहती हैं | रिलीज़ से पहले अनुमोदित नवीनतम स्थिर निचली सीमाएँ |
| सुरक्षा टूलिंग | वर्तमान निचली सीमाएँ pyproject.toml के security extra में रहती हैं | रिलीज़ से पहले अनुमोदित वर्तमान स्कैनर निचली सीमाएँ |
| रिलीज़ टूलिंग | हैश-लॉक किया गया क्लोज़र scripts/release/requirements-build-linux.txt में रहता है | रिलीज़ वर्कफ़्लो --require-hashes के साथ इंस्टॉल करता है; स्थानीय स्क्रिप्ट बदलती डिपेंडेंसी को चुपचाप इंस्टॉल करने के बजाय build के पहले से मौजूद होने की माँग करती हैं |
| दस्तावेज़ टूलिंग | वर्तमान रेंज site/package.json में रहती हैं; सटीक समाधान site/package-lock.json में रहता है | लॉकफ़ाइल रिफ़्रेश के बाद npm outdated कोई बासी दस्तावेज़ डिपेंडेंसी नहीं लौटाता |
| GitHub Actions | वर्तमान रिलीज़ के लिए मौजूदा SHA पिन बनाए रखे गए; SLSA पुन: प्रयोज्य वर्कफ़्लो प्रलेखित टैग-पिन अपवाद बना रहता है | सार्वजनिक CI पुन: रन हरा है; रिलीज़-सतह की उथल-पुथल से बचने के लिए व्यापक action-मेजर अपग्रेड जानबूझकर डिपेंडेंसी-ऑटोमेशन PR पर छोड़ दिए गए हैं |
| npm पैकेजिंग | केवल-मैनुअल publish-npm.yml वर्कफ़्लो; कोई स्वचालित रिलीज़ ट्रिगर नहीं | एकमात्र सार्वजनिक npm पैकेज @ahmed-g-gad/apothem है; प्रकाशन रिलीज़ तत्परता पास होने के बाद चलता है |
लॉकिंग
Python लॉक फ़ाइलें योगदानकर्ता द्वारा माँग पर जनरेट की जाती हैं। उन्हें कमिट नहीं किया जाता क्योंकि Apothem का रनटाइम क्लोज़र छोटा है, CLI कई Python माइनर संस्करणों का समर्थन करता है, और CI जानबूझकर नवीनतम मेल खाते टूलिंग संस्करणों का अभ्यास करता है।
# Astral uv:
uv pip install -e ".[dev,security,release]"
uv pip freeze > requirements.dev.lock
# pip-tools:
pip-compile --extra=dev --extra=security --extra=release -o requirements.dev.lock pyproject.toml
# Plain pip:
pip install -e ".[dev,security,release]"
pip freeze > requirements.dev.lockवेबसाइट अलग है: site/package-lock.json कमिट किया जाता है और CI npm ci का उपयोग
करता है, इसलिए रेंडर की गई दस्तावेज़ साइट में एक पुनरुत्पादनीय Node क्लोज़र होता है।
औचित्य
- Python के लिए रेंज पिन क्यों? CLI एक व्यापक Python मैट्रिक्स का समर्थन करता है और CI को उपयोगकर्ताओं के टकराने से पहले वर्तमान टूलिंग के साथ संगतता समस्याओं को उजागर करना चाहिए।
- कमिट किया गया Node लॉक क्यों? वेबसाइट एक तैनात स्थिर आर्टिफ़ैक्ट है; लॉकफ़ाइल
उस सार्वजनिक सतह के लिए नियतात्मक
npm ciबिल्ड देती है। - SHA-पिन की गई Actions क्यों? टैग परिवर्तनीय हैं; SHA अपरिवर्तनीय हैं। Renovate पिन की गई SHA को अपडेट करता है, जबकि रिलीज़ गेट किसी भी जानबूझकर रोक को रिकॉर्ड करता है।
लेखकत्व हेडर — प्रति-फ़ाइल SPDX लाइसेंस लाइन
प्रत्येक फ़ाइलप्रकार के लिए उपयुक्त टिप्पणी सिंटैक्स में कैनोनिकल एकल-लाइन हेडर का उपयोग करते हुए प्रति-फ़ाइल SPDX लाइसेंस आइडेंटिफ़ायर मार्कर परिभाषित और प्रवर्तित करें।
प्लान अनुशासन — प्रोजेक्ट-स्थानीय क्षणभंगुर वर्किंग मेमोरी
.apothem/plans/ (लीगेसी .plans/ ट्री को apothem migrate-workspace के माध्यम से अपग्रेड किया जाता है) में प्रोजेक्ट-स्थानीय क्षणभंगुर वर्किंग मेमोरी को frontmatter स्कीमा, जीवनचक्र संक्रमण, ADR में पदोन्नति, और हुक तथा सत्यापकों के माध्यम से प्रवर्तन के साथ प्रबंधित करें।