سياسة الشارات
تحديد مصادر الشارات الديناميكية والثابتة لملف README، شاملةً حالة سير العمل الأصلية لـ GitHub، وJSON نقطة نهاية shields.io، وأشكال الشارات الثابتة.
هذه الوثيقة هي المرجع الكانوني لشريط الشارات في README والبنية التحتية التي تنشر مصادر بياناته الديناميكية. كل شارة في README الخاص بالمشروع تُحلّ عبر أحد الأشكال الثلاثة المحددة هنا؛ والشارات الجديدة المضافة مستقبلًا تتبع الأشكال ذاتها أو تُرفض عند المراجعة.
1. الخلفية
عناوين https://img.shields.io/badge/X-Y-Z الثابتة لا تتغير من تلقاء
نفسها أبدًا، فتنحرف عن الحالة الحقيقية للمشروع — تظل شارة
release-vN-blue تعرض vN بعد طرح vN+1
بوقت طويل. لذلك تتطلب السياسة أشكالًا ديناميكية لكل قيمة تتحرك، وتحجز الشارات
الثابتة للمجموعة الصغيرة من القيم (الرخصة، إصدار Python المستهدف)
التي نادرًا ما تتغير، حيث يكون الشكل الثابت صادقًا.
2. العمارة
ثلاثة أشكال تغطّي كل شارة في المشروع:
- شارات حالة سير العمل الأصلية لـ GitHub. عنوان شارة سير العمل
يأخذ الشكل
https://github.com/<owner>/<repo>/actions/workflows/<file>/badge.svgويعكس آخر تشغيل على الفرع الافتراضي. تقدّم GitHub الشارة من البيانات الوصفية العامة للمستودع. - شارات نقطة نهاية 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 ناجح. تُبقي شارات نقطة النهاية المقاييس تحت نشر يتحكّم فيه المشروع بدلًا من مخزن قابل للتغيير تابع لطرف ثالث. - الشارات الثابتة لـ shields.io. تأخذ الشارة الثابتة الشكل
https://img.shields.io/badge/<label>-<message>-<color>دون مصدر بيانات تفاعلي. محجوزة للقيم التي نادرًا ما تتغير فعلًا (مُعرّف الرخصة، إصدار Python المستهدف).
نشر مقاييس المشروع عبر Gist العامة مُستبعَد عن قصد. نقاط نهاية shields.io فوق النطاق الذي يتحكّم فيه المشروع هي البديل الكانوني.
3. المواصفات لكل شارة
| الشارة | الشكل | المصدر | شكل العنوان |
|---|---|---|---|
| حالة CI | أصلي لـ GitHub | .github/workflows/ci.yml | https://github.com/ahmed-g-gad/apothem/actions/workflows/ci.yml/badge.svg?branch=main |
| آخر إيداع | أصلي لـ GitHub | البيانات الوصفية للمستودع | https://img.shields.io/github/last-commit/ahmed-g-gad/apothem |
| الرخصة | ثابت shields.io | LICENSE (MIT) | https://img.shields.io/badge/License-MIT-yellow.svg |
| آخر إصدار | نقطة نهاية shields.io | badges/release.json | https://img.shields.io/endpoint?url=https://apothem.ahmedgad.com/badges/release.json |
| التغطية | نقطة نهاية shields.io | badges/coverage.json | https://img.shields.io/endpoint?url=https://apothem.ahmedgad.com/badges/coverage.json |
| الأمان | نقطة نهاية shields.io | badges/security.json | https://img.shields.io/endpoint?url=https://apothem.ahmedgad.com/badges/security.json |
| سلسلة التوريد | نقطة نهاية shields.io | badges/supply-chain.json | https://img.shields.io/endpoint?url=https://apothem.ahmedgad.com/badges/supply-chain.json |
| التوثيق | نقطة نهاية shields.io | badges/docs.json | https://img.shields.io/endpoint?url=https://apothem.ahmedgad.com/badges/docs.json |
| إصدار Python | ثابت shields.io | pyproject.toml python_requires | https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white |
يعمل CodeQL كسير عمل مخصّص في .github/workflows/codeql.yml
يحلّل سطحَي Python وActions؛ ومهمة security-scan
في ci.yml تشغّل bandit فقط، تاركةً نشر نتائج
CodeQL لـ codeql.yml. تستهلك شارة الأمان الـ
JSON الخاص بنقطة النهاية المنشور من سير عمل badges بدلًا
من شارة سير عمل أصلية لـ GitHub، ممّا يبقي الشارة ثابتة عبر طوبولوجيا
الماسح الأساسية.
4. آلية نشر الـ JSON
تُنتَج ملفات JSON الخاصة بنقاط النهاية بواسطة
.github/workflows/badges.yml. سير العمل:
- يُشغَّل عند
workflow_runبعد اكتمال سير عملci(وعندworkflow_dispatchاليدوي لإعادة النشر دون تشغيل CI). - يحلّ أحدث وسم من
git describe --tags --abbrev=0واستنتاج CI الأب من حدثworkflow_run. - يولّد كل JSON عبر
jq -nبحيث يطابق الخرج بدقة مخطط نقطة نهاية shields.io (schemaVersion: 1، إضافةً إلىlabelوmessageوcolor). - يتحقق من كل JSON مُخرَج باستخدام
jq -eقبل الرفع. - يرفع الدليل كأثر سير عمل باسم
badges.
يُتولّى نشر الآثار إلى apothem.ahmedgad.com/badges/ بواسطة
.github/workflows/publish-static-site.yml. أثناء بناء الموقع،
يُنزّل ذلك السير أحدث أثر badges ناجح ويهيّئه تحت
site/dist/badges/. إذا كان الأثر غائبًا أو منتهي الصلاحية، فإن
الموقع يُنشر مع ذلك ويسجّل أثر الشارة المفقود في سجلات سير العمل بدلًا من نشر
JSON معطوب.
5. بروتوكول الصيانة
أضف شارة جديدة بتحديد الشكل أولًا:
- إذا كانت الشارة تعكس حالة تشغيل سير عمل CI، فضّل الشكل الأصلي لـ GitHub. عنوان الشارة مثبّت بملف سير العمل؛ ولا حاجة إلى بنية تحتية للنشر.
- إذا كانت الشارة تعكس مقياسًا (عددًا، أو نسبة مئوية، أو سلسلة إصدار، أو تسمية
مُدرّجة) يتحدّث مع الوقت، فاستخدم شكل نقطة نهاية shields.io. أضف
خطوة توليد JSON إلى
.github/workflows/badges.ymlإلى جانب الخمس الموجودة، وأضف عنوان المستهلكapothem.ahmedgad.com/badges/<name>.jsonإلى شريط الشارات في README. - إذا كانت الشارة تعكس قيمة نادرًا ما تتغير فعلًا (الرخصة، أو هدف اللغة، أو وضع الحوكمة)، فاستخدم الشكل الثابت لـ shields.io. وثّق وتيرة التغيير في جدول الشارات في هذا الملف عند إضافة الشارة.
تقاعد شارة بإزالتها من README أولًا، ثم إزالة خطوة توليد JSON الخاصة بها من سير عمل badges، ثم إزالة صفّها من جدول الشارات أعلاه. أبقِ الحذف ذرّيًا حتى لا يشير README أبدًا إلى أثر JSON لا ينتجه سير العمل.
6. المراجع المتقاطعة
- سير عمل CI الذي تعكس شارة CI الأصلية لـ GitHub
حالة تشغيله:
.github/workflows/ci.yml. - سير عمل badges الذي ينشر ملفات JSON الخاصة بنقاط النهاية:
.github/workflows/badges.yml. - نطاق الموقع الثابت الذي يقدّم ملفات JSON:
apothem.ahmedgad.com. - مرجع مخطط نقطة نهاية shields.io: https://shields.io/badges/endpoint-badge.