مخطّط خط أنابيب CI/CD

الخريطة البنيوية لسير عمل البناء · التحقّق · النشر الذي يُبوِّب كلّ تغيير في منظومة Apothem. يُثبِّت هذا المستند سطح التصوير؛ أمّا ملفّات سير العمل الفعلية لـGitHub Actions وأدوات الإصدار فتُوضَع لاحقًا ضمن تثبيت الجاهزية للإنتاج.

شكل خط الأنابيب

%%{ init: { "theme": "neutral" } }%%
%% verified: 2026-04-27 %%
%% provenance: pyproject.toml + scripts/dev/validate_ecosystem.py + scripts/dev/validate_hooks.py %%
%% cross-reference: site/content/docs/developer-guide.mdx (contributor workflow) %%
flowchart LR
    accTitle: CI/CD pipeline shape
    accDescr: Left-to-right flowchart of the apothem CI CD pipeline showing build, test, lint, type-check, security scan, docs build, package, sign, and publish stages with branch protection gates between them.
    subgraph Trigger["Trigger surface"]
        PR["Pull request opened or updated"]
        PUSH["Push to main"]
        TAG["Tag release vX.Y.Z"]
    end
    subgraph Static["Static analysis lane"]
        LINT["Ruff lint + format check"]
        TYPE["Mypy strict"]
        MD["markdownlint"]
        FRONT["Frontmatter validator"]
    end
    subgraph Test["Test lane"]
        PYTEST["pytest tests/hooks"]
        ECO["validate_ecosystem.py"]
        CHAOS["chaos_pass.py (release lane)"]
        BENCH["src/apothem/benchmarks/ (release lane)"]
    end
    subgraph Security["Security lane"]
        SECRETS["Secret scan"]
        SBOM["SBOM generation"]
        LICENSE["License audit"]
    end
    subgraph Publish["Publish lane (tags only)"]
        SIGN["Signed-tag verification"]
        ATTEST["Provenance attestation"]
        DOCS["Project website publish"]
        RELEASE["Release notes from CHANGELOG.md"]
    end
    PR --> Static
    PR --> Test
    PR --> Security
    PUSH --> Static
    PUSH --> Test
    PUSH --> Security
    TAG --> Static
    TAG --> Test
    TAG --> Security
    TAG --> Publish
    Static --> GATE{All lanes green?}
    Test --> GATE
    Security --> GATE
    GATE -->|yes| MERGE[Merge / publish]
    GATE -->|no| BLOCK[Block · surface failures · request fix]
    Publish --> MERGE

أدوار المسارات

• مسار التحليل الساكن — تغذية راجعة سريعة. يغطّي Ruff أسلوب Python ومجموعة قواعد منتقاة؛ ويفرض mypy انضباط الأنواع عند strict؛ ويضبط markdownlint سطح التوثيق؛ ويُبوِّب مُتحقِّق الـfrontmatter امتثال مخطّط القِطَع للقواعد والمهارات والعاملين المُفوَّضين والأوامر.
• مسار الاختبار — يُشغِّل pytest tests/hooks بيئة تشغيل الـ hook ضدّ مصفوفة الأحداث الكاملة؛ وvalidate_ecosystem.py هو البوّابة البنيوية الرئيسية للاتّساق عبر القِطَع؛ ويُفعَّل chaos_pass.py ومجموعة المقاييس المرجعية حسب الصنف تحت src/apothem/benchmarks/ على مسار الإصدار لالتقاط التدهور تحت المدخلات المتدهورة وانحدارات ميزانية وقت التشغيل.
• مسار الأمن — يلتقط فحص الأسرار الاعتمادات المُودَعة بالخطأ؛ ويُبوِّب توليد SBOM وعمليات تدقيق الترخيص سطح سلسلة التوريد لأيّ تثبيت جاهزية للإنتاج.
• مسار النشر — لا يعمل إلّا على الإصدارات الموسومة. يؤكّد التحقّق من الوسم المُوقَّع منشأ فرع الإصدار؛ ويُنشَر موقع المشروع من site/dist/ إلى هدف GitHub Pages؛ وتُشتَقّ ملاحظات الإصدار من تنسيق Keep-A-Changelog في CHANGELOG.md.

التهيئة الملموسة

تُثبَّت ملفّات سير العمل الفعلية (.github/workflows/ci.yml، .github/workflows/release.yml، وغيرها) أثناء بناء منظومة الجاهزية للإنتاج. يُعرِّف هذا المخطّط الشكل المعياري الذي تعكسه كلّ تهيئة مستقبلية.

مراجع متقاطعة موثوقة

• pyproject.toml — مصدر الحقيقة لتهيئة Ruff / mypy / pytest.
• scripts/dev/validate_ecosystem.py — البوّابة الرئيسية عبر القِطَع.
• scripts/dev/validate_hooks.py — التحقّق البنيوي الخاصّ بالـhook.
• scripts/dev/chaos_pass.py — مسح خصومي لكلّ hook مُهيَّأ.
• src/apothem/benchmarks/ — مُتحقِّقو ميزانية وقت التشغيل حسب الصنف.
• site/content/docs/developer-guide.mdx — سير عمل المُساهِم الموجَّه للمُشغِّل.
• CHANGELOG.md — مصدر ملاحظات الإصدار.