سياسة الشارات

هذه الوثيقة هي المرجع المعتمد لشريط الشارات في README وللبنية التحتية التي تنشر مصادر بياناته الديناميكية. كل شارة في README المشروع تُحَلّ عبر أحد الأشكال الثلاثة المحدّدة هنا؛ والشارات الجديدة التي تُضاف مستقبلًا تتبع الأشكال نفسها وإلا رُفِضت في المراجعة.

1. الخلفيةCopy Anchor Link

عناوين https://img.shields.io/badge/X-Y-Z الثابتة لا تتغيّر من تلقاء نفسها أبدًا، فتبتعد عن الحالة الحقيقية للمشروع — إذ تظلّ شارة release-vN-blue تعرض vN لوقت طويل بعد شحن vN+1. لذلك تشترط السياسة أشكالًا ديناميكية لكل قيمة متغيّرة، وتقصر الشارات الثابتة على المجموعة الصغيرة من القيم (الرخصة، ونسخة Python المستهدفة) التي نادرًا ما تتغيّر، حيث يكون الشكل الثابت صادقًا.

2. المعماريةCopy Anchor Link

أربعة أشكال تغطّي كل شارة في المشروع:

1. شارات حالة سير العمل الأصلية في GitHub. يأخذ عنوان شارة سير العمل الشكل https://github.com/<owner>/<repo>/actions/workflows/<file>/badge.svg ويعكس آخر تشغيل على الفرع الافتراضي. ويقدّم GitHub الشارة من البيانات الوصفية العامة للمستودع.
2. شارات نقاط نهاية shields.io. تَحُلّ شارة نقطة نهاية shields.io عنوانًا من الشكل https://img.shields.io/endpoint?url=<published-json> حيث يتوافق ملف JSON مع مخطط نقطة نهاية shields.io (schemaVersion، وlabel، وmessage، وcolor). ويقع ملف JSON المنشور في apothem.ahmedgad.com/badges/*.json؛ ويُولِّد محتواه سيرُ عمل CI في كل تشغيل CI ناجح. وتُبقي شارات نقاط النهاية المقاييسَ تحت نشر يتحكّم فيه المشروع بدلًا من مخزن قابل للتعديل لدى طرف ثالث.
3. الشارات الثابتة من shields.io. تأخذ الشارة الثابتة الشكل https://img.shields.io/badge/<label>-<message>-<color> دون مصدر بيانات تفاعلي. وهي مقصورة على القيم التي نادرًا ما تتغيّر فعلًا (مُعرِّف الرخصة، ونسخة Python المستهدفة).
4. شارات السجلّ وبطاقة التقييم. شارة يحسب قيمتها طرف ثالث من بيانات عامة يملكها أصلًا: سجلّ npm (النسخة والتنزيلات، ويعرضها shields.io) وواجهة برمجة OpenSSF Scorecard. لا ينشر المشروع أي شيء لهذه الشارات؛ فالطرف الثالث هو المصدر.

نشر مقاييس المشروع عبر Gist عامة مُستبعَد بحكم التصميم. ونقاط نهاية shields.io على النطاق الذي يتحكّم فيه المشروع هي البديل المعتمد.

3. المواصفات لكل شارةCopy Anchor Link

يسرد الجدول شريط الشارات في README بالترتيب. ويُعلِّم العمود الأخير الشارات التي لا تظهر صورتها إلا ما دام المستودع عامًا: فـ GitHub لا يقدّم شارة سير العمل لمستودع خاص إلا للأعضاء الذين سجّلوا الدخول، وScorecard لا يفحص إلا المستودعات العامة.

لا يُفتَح هدف الرابط لأي شارة على github.com (الإصدارات، وسير العمل، وملف الرخصة، والمسائل) إلا ما دام المستودع عامًا.

ينشر سير عمل الشارات أيضًا ملفات نقاط النهاية coverage.json وsecurity.json وsupply-chain.json وdocs.json لشارات مستقبلية؛ ولا يعرضها README اليوم.

يعمل CodeQL بوصفه سير عمل مخصّصًا هو .github/workflows/codeql.yml يحلّل سطحَي Python وActions؛ أمّا مهمة security-scan في ci.yml فلا تُشغِّل إلا bandit، تاركةً نشر CodeQL SARIF لـ codeql.yml. وتستهلك شارة الأمان ملف JSON لنقطة النهاية الذي ينشره سير عمل الشارات بدلًا من شارة سير عمل أصلية في GitHub، فتبقى الشارة مستقرّة مهما تغيّرت بنية الماسحات الكامنة.

4. آلية نشر JSONCopy Anchor Link

يُنتِج .github/workflows/badges.yml ملفات JSON لنقاط النهاية. وسير العمل هذا:

• يُطلَق عند workflow_run بعد اكتمال سير العمل ci (وعند workflow_dispatch اليدوي لإعادة النشر دون تشغيل CI).
• يحدّد أحدث وسم إصدار عبر git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' على نسخة مسحوبة بالسجلّ الكامل (fetch-depth: 0؛ ففي نسخة مسحوبة بعمق 1 لا يمكن الوصول إلى أي كوميت موسوم وتعرض الشارة unreleased)، ونتيجة CI الأب من حدث workflow_run.
• يُولِّد كل ملف JSON عبر jq -n بحيث يطابق الخرج بصرامة مخطط نقطة نهاية shields.io (schemaVersion: 1، إضافةً إلى label وmessage وcolor).
• يتحقّق من كل ملف JSON مُصدَر بـ jq -e قبل الرفع.
• يرفع الدليل بوصفه مُنتَج سير عمل باسم badges.

يتولّى .github/workflows/publish-static-site.yml نشر المُنتَجات إلى apothem.ahmedgad.com/badges/. فأثناء بناء الموقع، يُنزِّل سير العمل ذاك أحدث مُنتَج badges ناجح ويُجهِّزه تحت site/dist/badges/. وإذا كان المُنتَج غائبًا أو منتهي الصلاحية، يُنشَر الموقع رغم ذلك ويُسجِّل غياب مُنتَج الشارات في سجلات سير العمل بدلًا من نشر JSON معطوب.

5. بروتوكول الصيانةCopy Anchor Link

أضِف شارة جديدة بتحديد شكلها أولًا:

• إذا كانت الشارة تعكس حالة تشغيل سير عمل CI، ففضِّل الشكل الأصلي في GitHub. فعنوان الشارة يحدّده ملف سير العمل؛ ولا تلزم أي بنية تحتية للنشر.
• إذا كانت الشارة تعكس مقياسًا (عددًا، أو نسبة مئوية، أو سلسلة نسخة، أو تسمية متدرّجة) يتحدّث مع الوقت، فاستخدم شكل نقطة نهاية shields.io. أضِف خطوة توليد JSON إلى .github/workflows/badges.yml إلى جانب الخطوات الخمس الموجودة، وأضِف عنوان المستهلِك apothem.ahmedgad.com/badges/<name>.json إلى شريط الشارات في README.
• إذا كانت الشارة تعكس قيمة نادرًا ما تتغيّر فعلًا (الرخصة، أو اللغة المستهدفة، أو وضع الحوكمة)، فاستخدم الشكل الثابت من shields.io. ووثِّق وتيرة التغيير في جدول المواصفات لكل شارة في هذا الملف عند إضافة الشارة.

أوقِف شارة بإزالتها من README أولًا، ثم إزالة خطوة توليد JSON الخاصة بها من سير عمل الشارات، ثم إزالة صفّها من جدول المواصفات لكل شارة أعلاه. واجعل الحذف ذرّيًا كي لا يشير README أبدًا إلى مُنتَج JSON لا يُنتِجه سير العمل.

6. المراجع المتقاطعةCopy Anchor Link

• سير عمل CI الذي تعكس شارة CI الأصلية في GitHub حالة تشغيله: .github/workflows/ci.yml.
• سير عمل الشارات الذي ينشر ملفات JSON لنقاط النهاية: .github/workflows/badges.yml.
• نطاق الموقع الثابت الذي يقدّم ملفات JSON: apothem.ahmedgad.com.
• مرجع مخطط نقطة نهاية shields.io: https://shields.io/badges/endpoint-badge.