بيان تثبيت الاعتماديات
سياسة الإعلان عن الاعتماديات تغطي نطاقات بيئة تشغيل Python، وأدوات التطوير، وملفات قفل أدوات الإصدار، والحدود الدنيا للإصدارات المُصادَق عليها لكل سطح بناء.
الموقف المُصادَق عليه لكيفية إعلان Apothem عن الاعتماديات وتثبيتها وقفلها. الجمهور: المساهمون والمستهلكون في المراحل اللاحقة ممّن يحتاجون إلى فهم نموذج قابلية إعادة الإنتاج.
الموقف
Apothem هو واجهة سطر أوامر Python بمجموعة صغيرة من اعتماديات وقت التشغيل،
إضافةً إلى سلسلة أدوات أكبر للتطوير والتدقيق والإصدار والتوثيق. تستخدم اعتماديات
وقت التشغيل حدودًا دنيا متحفظة في pyproject.toml؛ ويُودِع الموقع
site/package-lock.json؛ وتُثبَّت GitHub Actions بـSHA غير قابل للتغيير
مع تعليقات الإصدار، وتُرقَّى عبر Renovate.
| الصنف | الإعلان | سياسة القفل |
|---|---|---|
| اعتماديات وقت تشغيل Python | [project.dependencies] في pyproject.toml | نطاقات بحد أدنى؛ بلا قفل وقت تشغيل Python مُودَع |
| أدوات التطوير / الأمان | extras الخاصة بـ[project.optional-dependencies] | نطاقات بحد أدنى؛ يُثبِّت 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 | مراجع uses: مُثبَّتة بـSHA مع تعليقات الإصدار | يقترح Renovate التحديثات؛ وتحمل الاستثناءات علامات action-pinning-exempt: |
مصادقة الإصدار
| السطح | الحالة المُصادَق عليها | المسوّغ |
|---|---|---|
| اعتماديات وقت التشغيل | تعيش الحدود الدنيا الحالية في pyproject.toml [project.dependencies] | حدود دنيا مستقرة حالية مُصادَق عليها قبل الإصدار؛ بلا مُعيق CVE معروف لوقت التشغيل |
| أدوات التطوير | تعيش الحدود الدنيا الحالية في extra dev من pyproject.toml | أحدث حدود دنيا مستقرة مُصادَق عليها قبل الإصدار |
| أدوات الأمان | تعيش الحدود الدنيا الحالية في extra security من pyproject.toml | حدود دنيا حالية للماسحات مُصادَق عليها قبل الإصدار |
| أدوات الإصدار | يعيش الإغلاق المقفول بالتجزئة في scripts/release/requirements-build-linux.txt | يُثبِّت سير عمل الإصدار بـ--require-hashes؛ وتشترط النصوص المحلية وجود build مسبقًا بدلًا من تثبيت اعتماديات متحركة بصمت |
| أدوات التوثيق | تعيش النطاقات الحالية في site/package.json؛ وتعيش الحلول الدقيقة في site/package-lock.json | لا يُرجِع npm outdated أي اعتمادية توثيق بائتة بعد تحديث ملف القفل |
| GitHub Actions | تُستبقى تثبيتات SHA الموجودة للإصدار الحالي؛ ويبقى سير عمل SLSA القابل لإعادة الاستخدام الاستثناءَ المُوثَّق المُثبَّت بوسم | إعادة تشغيل CI العام خضراء؛ وتُترَك ترقيات الإصدارات الكبرى الواسعة لـactions عمدًا لطلبات دمج أتمتة الاعتماديات لتفادي اضطراب سطح الإصدار |
| تحزيم npm | سير عمل publish-npm.yml يدوي فقط؛ بلا مُحفِّز إصدار آلي | الحزمة npm العامة الوحيدة هي @ahmed-g-gad/apothem؛ ويُشغَّل النشر بعد اجتياز جاهزية الإصدار |
القفل
تُولَّد ملفات قفل Python عند الطلب من قِبَل المساهم. ولا تُودَع لأن إغلاق وقت تشغيل Apothem صغير، ولأن واجهة سطر الأوامر تدعم عدة إصدارات فرعية من 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؟ تدعم واجهة سطر الأوامر مصفوفة Python واسعة، وينبغي لـCI أن يكشف مشكلات التوافق مع الأدوات الحالية قبل أن يصطدم بها المستخدمون.
- لماذا قفل Node مُودَع؟ الموقع أثر ساكن مُنشَر؛ ويمنح ملف القفل عمليات بناء
npm ciحتمية لذلك السطح العام. - لماذا Actions مُثبَّتة بـSHA؟ الوسوم قابلة للتغيير؛ أما SHA فغير قابلة للتغيير. يُحدِّث Renovate قيم SHA المُثبَّتة، بينما تُسجِّل بوابة الإصدار أي تأجيل مقصود.
ترويسة الكِتابة (Authorship Header) — سطر رخصة SPDX لكل ملف
تعريف وفرض علامات مُعرِّف رخصة SPDX لكل ملف باستخدام ترويسات أحادية السطر كنسية بصيغة التعليق المناسبة لكل نوع ملف.
انضباط الخطط — ذاكرة عمل عابرة محلية للمشروع
إدارة ذاكرة عمل عابرة محلية للمشروع في .apothem/plans/ (تُرقَّى شجرة .plans/ القديمة عبر apothem migrate-workspace) مع مخطط الواجهة الأمامية وانتقالات دورة الحياة والترقية إلى سجلات قرار معمارية والفرض عبر الخطافات والمُتحقِّقات.