डिपेंडेंसी पिनिंग मैनिफ़ेस्ट
डिपेंडेंसी घोषणा नीति, जो Python रनटाइम रेंज, डेवलपमेंट टूलिंग, रिलीज़-टूल लॉक फ़ाइलों, और प्रत्येक बिल्ड सतह के लिए अनुमोदित संस्करण निचली सीमाओं को कवर करती है।
Apothem डिपेंडेंसी को कैसे घोषित, पिन, और लॉक करता है, इसके लिए अनुमोदित मुद्रा। श्रोता: योगदानकर्ता और डाउनस्ट्रीम उपभोक्ता जिन्हें पुनरुत्पादनीयता मॉडल समझने की आवश्यकता है।
मुद्रा
Apothem एक Python CLI है जिसमें रनटाइम डिपेंडेंसी का एक छोटा सेट है, साथ ही एक
बड़ी डेवलपमेंट, ऑडिट, रिलीज़, और दस्तावेज़ टूलचेन है। रनटाइम डिपेंडेंसी
pyproject.toml में रूढ़िवादी निचली सीमाओं का उपयोग करती हैं; वेबसाइट
site/package-lock.json को कमिट करती है; GitHub Actions संस्करण टिप्पणियों के साथ
अपरिवर्तनीय SHA द्वारा पिन की जाती हैं और Dependabot द्वारा अपग्रेड की जाती हैं।
| श्रेणी | घोषणा | लॉक नीति |
|---|---|---|
| रनटाइम Python डिपेंडेंसी | pyproject.toml में [project.dependencies] | उपयोगकर्ताओं के लिए निचली-सीमा रेंज; पैकेज के साथ कोई Python रनटाइम लॉक नहीं आता। CI इन डिपेंडेंसी का हैश-लॉक किया गया क्लोज़र इंस्टॉल करता है (CI डिपेंडेंसी लॉक देखें) |
| डेवलपमेंट / सुरक्षा टूलिंग | [project.optional-dependencies] एक्स्ट्रा | निचली-सीमा रेंज, सिवाय ruff और mypy के, जिन्हें dev एक्स्ट्रा ठीक उन्हीं संस्करणों पर पिन करता है जिन्हें CI चलाता है (ruff के लिए CI टूल लॉक देखें); CI dev एक्स्ट्रा को हैश-लॉक किए गए क्लोज़र से इंस्टॉल करता है (CI डिपेंडेंसी लॉक देखें) |
| रिलीज़ टूलिंग | रिलीज़ वर्कफ़्लो के लिए scripts/release/requirements-build-linux.txt; स्थानीय बिल्ड के लिए [project.optional-dependencies] में release एक्स्ट्रा | रिलीज़ वर्कफ़्लो के लिए हैश-लॉक; रिलीज़ टूलिंग क्लोज़र से जनरेट किया गया। release एक्स्ट्रा एक निचली-सीमा रेंज है |
| CI pip | scripts/ci/requirements-ci-pip.txt | हैश-लॉक: एक pip==X.Y.Z पिन, उसके wheel और sdist के हैश के साथ, जिसे pip अपग्रेड करने वाला हर वर्कफ़्लो --require-hashes -r के साथ इंस्टॉल करता है। Dependabot अपग्रेड प्रस्तावित करता है और हैश दोबारा लिखता है; scripts/dev/check_pip_pin_drift.py पिन को pip 26.2 या उससे नए संस्करण पर रखता है |
| CI डिपेंडेंसी लॉक | scripts/ci/requirements-ci-dev.txt, -runtime.txt, -test.txt और -prereqs.txt | हैश-लॉक किए गए यूनिवर्सल क्लोज़र, जिन्हें uv pip compile से pyproject.toml से (या -prereqs.txt के लिए इंजन की होस्ट पूर्वापेक्षाओं से) कंपाइल किया जाता है। आधार एक लॉक तिथि है, जिसमें से 7-दिन की कूलडाउन अवधि घटाई जाती है; दोनों हर फ़ाइल में दर्ज होते हैं। इन्हें --require-hashes -r के साथ इंस्टॉल किया जाता है (पैकेज स्वयं --no-deps -e . के साथ)। जब तक scripts/dev/refresh_ci_locks.py इन्हें दोबारा जनरेट नहीं करता, CI लॉक किए गए संस्करणों का परीक्षण करता है; pip-audit.yml हर सप्ताह अनुमत नवीनतम संस्करणों का और लॉक का ऑडिट करता है। कोई लॉक अपने इनपुट को संतुष्ट न करे, तो tests/scripts/test_ci_locks_fresh.py विफल होता है |
| CI टूल लॉक | scripts/ci/requirements-ci-ruff.txt, -bandit.txt, -pip-audit.txt, -pip-licenses.txt और -pre-commit.txt | वर्कफ़्लो द्वारा चलाए जाने वाले हर टूल के लिए एक हैश-लॉक किया गया क्लोज़र। इसे वही स्क्रिप्ट scripts/dev/ci_lock_table.py के सटीक विनिर्देश से उसी लॉक तिथि और कूलडाउन के साथ कंपाइल करती है, और इसे --require-hashes -r के साथ इंस्टॉल किया जाता है। कोई वर्कफ़्लो टूल का संस्करण नहीं लिखता। pre-commit को Python 3.11 या उससे नया चाहिए, इसलिए उसके लॉक को भी; pip-audit का लॉक भी 3.11 के लिए कंपाइल किया जाता है, क्योंकि 3.10 का समर्थन करने वाले नवीनतम filelock में बिना सुधार वाली सुरक्षा एडवाइज़री हैं। CI pip के अलावा कोई लॉक pip को पिन नहीं करता |
| दस्तावेज़ साइट | site/package.json | site/package-lock.json कमिट किया गया और npm ci द्वारा उपभोग किया गया |
| VS Code पैकेजर | tools/vsce/package.json | tools/vsce/package-lock.json कमिट किया गया; रिलीज़ और प्रकाशन जॉब npm ci --ignore-scripts चलाते हैं |
| Channel-smoke हार्नेस CLI | tools/channel-smoke/package.json | tools/channel-smoke/package-lock.json कमिट किया गया और npm ci द्वारा उपभोग किया गया |
| GitHub Actions | संस्करण टिप्पणियों के साथ SHA-पिन की गई uses: रेफ़रेंस | Dependabot साप्ताहिक अपडेट प्रस्तावित करता है; अपवाद action-pinning-exempt: मार्कर रखते हैं |
रिलीज़ अनुमोदन
| सतह | अनुमोदित स्थिति | औचित्य |
|---|---|---|
| रनटाइम डिपेंडेंसी | वर्तमान निचली सीमाएँ pyproject.toml [project.dependencies] में रहती हैं | रिलीज़ से पहले अनुमोदित वर्तमान स्थिर निचली सीमाएँ; कोई ज्ञात रनटाइम CVE अवरोधक नहीं |
| डेवलपमेंट टूलिंग | वर्तमान निचली सीमाएँ pyproject.toml के dev एक्स्ट्रा में रहती हैं; ruff और mypy वहाँ सटीक पिन हैं | रिलीज़ से पहले अनुमोदित नवीनतम स्थिर निचली सीमाएँ; ruff और mypy दोनों हुक, CI और योगदानकर्ताओं के लिए एक-एक संस्करण पर पिन हैं, mypy हुक अपनी सूची की लाइब्रेरी को dev लॉक के संस्करणों पर पिन करता है, और इनमें अंतर होने पर tests/scripts/test_ci_tool_locks.py विफल होता है |
| सुरक्षा टूलिंग | वर्तमान निचली सीमाएँ pyproject.toml के security एक्स्ट्रा में रहती हैं | रिलीज़ से पहले अनुमोदित वर्तमान स्कैनर निचली सीमाएँ |
| रिलीज़ टूलिंग | हैश-लॉक किया गया क्लोज़र scripts/release/requirements-build-linux.txt में रहता है | रिलीज़ वर्कफ़्लो --require-hashes के साथ इंस्टॉल करता है; स्थानीय स्क्रिप्ट चुपचाप बदलती डिपेंडेंसी इंस्टॉल करने के बजाय यह माँग करती हैं कि build पहले से मौजूद हो |
| CI pip | हैश-लॉक किया गया पिन scripts/ci/requirements-ci-pip.txt में रहता है | pip 26.2 या उससे नया संस्करण CVE-2026-13346 को ठीक करता है; वर्कफ़्लो इसे --require-hashes के साथ इंस्टॉल करते हैं, इसलिए डाउनलोड को उसके प्रकाशित हैश से जाँचा जाता है |
| CI डिपेंडेंसी लॉक | हैश-लॉक किए गए क्लोज़र scripts/ci/requirements-ci-{dev,runtime,test,prereqs}.txt में रहते हैं | वर्कफ़्लो इन्हें --require-hashes के साथ इंस्टॉल करते हैं; हर फ़ाइल अपनी लॉक तिथि, कूलडाउन और कटऑफ़ दर्ज करती है, और फ़्रेशनेस परीक्षण इन्हें pyproject.toml के साथ तालमेल में रखता है |
| CI टूल लॉक | हैश-लॉक किए गए क्लोज़र scripts/ci/requirements-ci-{ruff,bandit,pip-audit,pip-licenses,pre-commit}.txt में रहते हैं | वर्कफ़्लो इन्हें --require-hashes के साथ इंस्टॉल करते हैं और टूल का कोई संस्करण नहीं लिखते; विनिर्देश scripts/dev/ci_lock_table.py में रहते हैं, और लॉक तिथि, कूलडाउन और कटऑफ़ डिपेंडेंसी लॉक के समान हैं |
| दस्तावेज़ टूलिंग | वर्तमान रेंज site/package.json में रहती हैं; सटीक समाधान site/package-lock.json में रहता है | लॉकफ़ाइल रिफ़्रेश के बाद npm outdated कोई बासी दस्तावेज़ डिपेंडेंसी नहीं लौटाता |
| GitHub Actions | वर्तमान रिलीज़ के लिए मौजूदा SHA पिन बनाए रखे गए; SLSA पुन: प्रयोज्य वर्कफ़्लो प्रलेखित टैग-पिन अपवाद बना रहता है, जिसे release.yml में action-pinning-exempt: टिप्पणी से चिह्नित किया गया है | सार्वजनिक CI पुन: रन हरा है; रिलीज़-सतह की उथल-पुथल से बचने के लिए व्यापक action-मेजर अपग्रेड जानबूझकर डिपेंडेंसी-ऑटोमेशन PR पर छोड़े गए हैं |
| npm पैकेजिंग | publish-npm.yml वर्कफ़्लो v*.*.* टैग पुश पर चलता है, workflow_dispatch फ़ॉलबैक के रूप में | एकमात्र सार्वजनिक npm पैकेज @ahmed-g-gad/apothem है; प्रकाशन release एनवायरनमेंट की ऑपरेटर-स्वीकृति की प्रतीक्षा करता है, जो scripts/release/check-release-ready.sh के पास होने के बाद दी जाती है |
लॉकिंग
योगदानकर्ताओं की अपनी Python लॉक फ़ाइलें माँग पर जनरेट की जाती हैं और कमिट नहीं की
जातीं: Apothem का रनटाइम क्लोज़र छोटा है और CLI कई Python माइनर संस्करणों का समर्थन
करता है। CI इसका अपवाद है। वह scripts/ci/ की हैश-लॉक की गई फ़ाइलें इंस्टॉल करता है:
चार डिपेंडेंसी लॉक (requirements-ci-dev.txt, -runtime.txt, -test.txt और
-prereqs.txt) और वर्कफ़्लो द्वारा चलाए जाने वाले हर टूल के लिए एक लॉक (-ruff.txt,
-bandit.txt, -pip-audit.txt, -pip-licenses.txt और -pre-commit.txt)।
python scripts/dev/refresh_ci_locks.py सभी नौ को एक लॉक तिथि के आधार पर कंपाइल करता
है, जिसमें से Dependabot की तरह 7-दिन की कूलडाउन अवधि घटाई जाती है। इसलिए CI उन रिलीज़
का परीक्षण करता है जो लॉक तिथि पर कम से कम एक सप्ताह पुरानी थीं, और फ़ाइलें रिफ़्रेश करने
से परीक्षण वाली रिलीज़ भी आगे बढ़ती हैं। हर फ़ाइल लॉक तिथि, कूलडाउन और उससे निकलने वाला
कटऑफ़ दर्ज करती है, और --check उसी कटऑफ़ को दोबारा बनाता है। कूलडाउन से नए किसी
तत्काल सुरक्षा सुधार के लिए --cooldown-days 0 के साथ रिफ़्रेश चलाना होगा, या
scripts/dev/ci_lock_table.py में उसके पैकेज के लिए कूलडाउन अपवाद जोड़ना होगा, जो केवल
उसी पैकेज के लिए कूलडाउन हटाता है। साप्ताहिक pip-audit.yml रन pyproject.toml द्वारा
अनुमत नवीनतम संस्करणों के साथ-साथ नौ लॉक का भी ऑडिट करता है, और एडवाइज़री के लिए OSV
सेवा से पूछता है। योगदानकर्ता पहले की तरह pip install -e ".[dev]" से इंस्टॉल करते हैं।
# 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 मैट्रिक्स का समर्थन करता है,
इसलिए
pyproject.tomlरूढ़िवादी निचली सीमाएँ रखता है। CI इन रेंज के हैश-लॉक किए गए क्लोज़र इंस्टॉल करता है, जिन्हें अनुरक्षकscripts/dev/refresh_ci_locks.pyसे रिफ़्रेश करता है (साप्ताहिक रिफ़्रेश का इरादा है), और साप्ताहिकpip-audit.ymlरन अनुमत नवीनतम संस्करणों को रिज़ॉल्व करता है, ताकि वर्तमान टूलिंग के साथ समस्याएँ सामने आएँ। - कमिट किया गया Node लॉक क्यों? वेबसाइट एक तैनात स्थिर आर्टिफ़ैक्ट है; लॉकफ़ाइल
उस सार्वजनिक सतह के लिए नियतात्मक
npm ciबिल्ड देती है। - SHA-पिन की गई Actions क्यों? टैग परिवर्तनीय हैं; SHA अपरिवर्तनीय हैं। Dependabot SHA अपग्रेड प्रस्तावित करता है और हर संस्करण टिप्पणी को दोबारा लिखता है, जबकि रिलीज़ गेट किसी भी जानबूझकर रोक को रिकॉर्ड करता है।
- अपडेट बॉट किसे नहीं छूता। Dependabot संस्करण अपडेट
(
.github/dependabot.yml) GitHub Actions पिन, वेबसाइट लॉकफ़ाइल, vsce पैकेजर लॉकफ़ाइल (tools/vsce), channel smoke द्वारा इंस्टॉल की जाने वाली हार्नेस-CLI लॉकफ़ाइल (tools/channel-smoke), CI द्वारा इंस्टॉल किए जाने वाले हैश-लॉक pip (scripts/ci/requirements-ci-pip.txt) और pre-commit हुक को कवर करते हैं।scripts/ciकी बाकी नौ फ़ाइलें ऐसे क्लोज़र हैं जिन्हेंscripts/dev/refresh_ci_locks.pyपूरा का पूरा दोबारा जनरेट करता है; इनमें से कोई pip को पिन नहीं करती, और उस फ़ोल्डर के लिए Dependabot संस्करण अपडेट केवल pip तक सीमित हैं।pyproject.tomlमें रनटाइम निचली सीमाएँ, हैश-लॉक की गई रिलीज़ आवश्यकताएँ,src/apothem/_vendor/vendor.txtमें वेंडर किया गया क्लोज़र औरpyproject.tomlके साथ तालमेल में पिन किए गए pre-commit हुक हाथ से बदले जाते हैं, क्योंकि एक अकेले पिन का अपग्रेड उन फ़ाइलों को तोड़ देगा जिनसे वे मेल खाते हैं। ruff और mypy हुक इन्हीं में से दो हैं:tests/scripts/test_ci_tool_locks.pyतब तक विफल होता है जब तकpyproject.tomlका सटीक ruff पिन, हुक rev, ruff लॉक और dev लॉक एक ही संस्करण न रखें, और जब तक सटीक mypy पिन, mypy हुक rev और उस हुक की सूची की लाइब्रेरी dev लॉक से मेल न खाएँ। इसलिए दोनों में से किसी भी टूल के लिए Dependabot सुरक्षा पुल रिक्वेस्ट को हाथ से अनुकूलित किया जाता है। वेबसाइट का@types/nodeमेजर उसकी Node निचली सीमा (enginesऔर.nvmrc, Node 22) का अनुसरण करता है, इसलिए Dependabot केवल उसके माइनर और पैच अपडेट प्रस्तावित करता है; उस मेजर को निचली सीमा के साथ ही बढ़ाएँ। संस्करण अपडेट npmoverridesब्लॉक को नहीं छूते। Dependabot सुरक्षा अपडेट फिर भी हर मैनिफ़ेस्ट को कवर करते हैं, इसलिए एक सुरक्षा पुल रिक्वेस्ट इनमें से किसी पिन का प्रस्ताव कर सकता है, या किसी override को बदल सकता है; उसे हाथ से अनुकूलित करें या बंद करें। - Dependabot पुल रिक्वेस्ट को मर्ज करना। रिपॉज़िटरी का squash डिफ़ॉल्ट PR शीर्षक
लेता है। कुछ Dependabot शीर्षक, अधिकतर समूहीकृत शीर्षक जो किसी डायरेक्टरी का नाम
लेते हैं, 72-वर्ण की squash विषय-पंक्ति से आगे निकल जाते हैं; PR Title जाँच उनका
नाम बताती है, और शीर्षक बदलने से वे ठीक हो जाते हैं। टूल लॉकफ़ाइल बदलने वाला पुल
रिक्वेस्ट कोई
ci.ymlजॉब नहीं चलाता, इसलिए npm audit वर्कफ़्लो उसका ऑडिट करता है और उसे इंस्टॉल करता है, vsce लॉकफ़ाइल के लिए VS Code एक्सटेंशन को पैकेज करता है और vsce रिलीज़ परीक्षण चलाता है, और channel-smoke लॉकफ़ाइल के लिए channel smoke वर्कफ़्लो चलता है। Markdown Lint वर्कफ़्लो pre-commit हुक पुल रिक्वेस्ट पर markdownlint हुक चलाता है; अन्य हुक CI में नहीं चलाए जाते, इसलिए उसे मर्ज करने से पहले उसकी ब्रांच परpre-commit run --all-filesचलाएँ।
लेखकत्व हेडर — प्रति-फ़ाइल SPDX लाइसेंस लाइन
प्रत्येक फ़ाइलप्रकार के लिए उपयुक्त टिप्पणी सिंटैक्स में कैनोनिकल एकल-लाइन हेडर का उपयोग करते हुए प्रति-फ़ाइल SPDX लाइसेंस आइडेंटिफ़ायर मार्कर परिभाषित और प्रवर्तित करें।
प्लान अनुशासन — प्रोजेक्ट-स्थानीय क्षणभंगुर वर्किंग मेमोरी
.apothem/plans/ में (पुराना .plans/ ट्री apothem migrate-workspace के माध्यम से अपग्रेड होता है) प्रोजेक्ट-स्थानीय क्षणभंगुर वर्किंग मेमोरी को frontmatter स्कीमा, जीवनचक्र संक्रमण, ADR में पदोन्नति, और हुक तथा वैलिडेटरों के माध्यम से प्रवर्तन के साथ प्रबंधित करें।