تأليف محوّل إطار عمل جديد

استخدم هذا الدليل التشغيلي عند تأليف محوّل إطار عمل جديد ليُدرَج بشكل أصيل في Apothem أو كحزمة طرف ثالث.

المتطلّبات المسبقةCopy Anchor Link

• الإلمام بـ بروتوكول HarnessAdapter
• فهم صيغة تهيئة إطار العمل المستهدف
• Python 3.10+

الخطواتCopy Anchor Link

1. نفِّذ المحوّلCopy Anchor Link

اتبع مثال تأليف محوّل إطار عمل لتنفيذ HarnessAdapter لإطار العمل المستهدف.

إذا كان المحوّل يكتب قالبًا نصيًا عاديًا (ملفًا ليس JSON ولا YAML) باستخدام mode: write_text وownership_class: operator-owned، فإن uninstall لا يحذف الملف إلا ما دام نسخة غير معدَّلة من قالب شحنه Apothem. وحين يغيّر إصدار لاحق القالب، أضف بصمة SHA-256 للنص السابق إلى قائمة earlier_digests في مُدخل البيان ذاك ضمن التغيير نفسه، وإلا ترك uninstall في مكانها كل نسخة غير معدَّلة كتبها الإصدار الأقدم. خذ بصمة النص عند وسم آخر إصدار باستخدام git show <tag>:<template path> | sha256sum؛ ويجب ألا يحمل القالب أي رمز مسار ${...}. يفشل tests/unit/test_template_digests.py حين لا يُؤخذ قالب مشحون في الحسبان.

2. اكتب صفحة التوثيقCopy Anchor Link

أنشئ site/content/docs/harnesses/<slug>.mdx يغطّي:

• تدفّق التثبيت
• تخطيط الملف التعريفي إلى التهيئة الأصلية
• محاذير التوافق
• وصفات التحقّق
• وصفات التحديث وإلغاء التثبيت
• سطح بوّابة المطابقة
• جدول استكشاف الأخطاء وإصلاحها
• جدول مقابض التهيئة

3. اكتب الاختباراتCopy Anchor Link

tests/packaging/test_<slug>_adapter.py
tests/unit/test_<slug>_adapter.py

الحد الأدنى لتغطية الاختبارات:

• test_install_creates_expected_files
• test_verify_passes_after_install
• test_uninstall_removes_files

4. تحقّق محليًاCopy Anchor Link

apothem install --harness <slug>
apothem verify --harness <slug>
python -m apothem.conformity.gate --all .

5. قدِّم طلب السحبCopy Anchor Link

افتح PR يتضمّن:

• تنفيذ المحوّل
• صفحة التوثيق في site/content/docs/harnesses/<slug>.mdx
• الاختبارات
• تسجيل نقطة الدخول في pyproject.toml، ومدخل HARNESS_REGISTRY في src/apothem/lib/harness_registry_data.py (مع رفع SUPPORTED_HARNESS_COUNT هناك)، والمعرّف في تعداد harnessId الخاص بـsrc/apothem/schemas/profile.schema.json
• مدخل في سجلّ التغييرات