Kebijakan lencana

Dokumen ini adalah referensi kanonik untuk deretan lencana README dan infrastruktur yang memublikasikan sumber data dinamisnya. Setiap lencana di README proyek di-resolve melalui salah satu dari tiga bentuk yang ditetapkan di sini; lencana baru yang ditambahkan di masa mendatang mengikuti bentuk yang sama atau ditolak saat tinjauan.

1. Latar belakangCopy Anchor Link

URL statis https://img.shields.io/badge/X-Y-Z tidak pernah berubah dengan sendirinya, sehingga menyimpang dari keadaan proyek yang sebenarnya — lencana release-vN-blue tetap menampilkan vN lama setelah vN+1 dirilis. Karena itu, kebijakan ini mensyaratkan bentuk dinamis untuk setiap nilai yang berubah, dan mencadangkan lencana statis untuk sekumpulan kecil nilai (lisensi, versi target Python) yang jarang berubah, yang bentuk statisnya jujur.

2. ArsitekturCopy Anchor Link

Empat bentuk mencakup setiap lencana dalam proyek:

1. Lencana status alur kerja native GitHub. URL lencana sebuah alur kerja berbentuk https://github.com/<owner>/<repo>/actions/workflows/<file>/badge.svg dan mencerminkan eksekusi terbaru pada branch default. GitHub menyajikan lencana dari metadata publik repositori.
2. Lencana endpoint shields.io. Lencana endpoint shields.io me-resolve URL https://img.shields.io/endpoint?url=<published-json> dengan JSON yang mematuhi skema endpoint shields.io (schemaVersion, label, message, color). JSON yang dipublikasikan berada di apothem.ahmedgad.com/badges/*.json; isinya dihasilkan oleh alur kerja CI pada setiap eksekusi CI yang berhasil. Lencana endpoint menjaga metrik di bawah publikasi yang dikendalikan proyek, bukan di penyimpanan pihak ketiga yang dapat diubah.
3. Lencana statis shields.io. Lencana statis berbentuk https://img.shields.io/badge/<label>-<message>-<color> tanpa sumber data reaktif. Dicadangkan untuk nilai yang memang jarang berubah (pengenal lisensi, versi target Python).
4. Lencana registri dan scorecard. Lencana yang nilainya dihitung pihak ketiga dari data publik yang sudah dimilikinya: registri npm (versi dan unduhan, dirender oleh shields.io) dan API OpenSSF Scorecard. Proyek tidak memublikasikan apa pun untuk lencana ini; pihak ketiga itulah sumbernya.

Publikasi metrik proyek melalui Gist publik dikecualikan secara desain. Endpoint shields.io di atas domain yang dikendalikan proyek adalah pengganti kanoniknya.

3. Spesifikasi per lencanaCopy Anchor Link

Tabel ini mencantumkan deretan lencana README secara berurutan. Kolom terakhir menandai lencana yang gambarnya hanya dirender selama repositori bersifat publik: GitHub menyajikan lencana alur kerja untuk repositori privat hanya kepada anggota yang masuk, dan Scorecard hanya memindai repositori publik.

Setiap target tautan lencana di github.com (rilis, alur kerja, berkas lisensi, isu) hanya terbuka selama repositori bersifat publik.

Alur kerja badges juga memublikasikan berkas endpoint coverage.json, security.json, supply-chain.json, dan docs.json untuk lencana di masa mendatang; README saat ini tidak menampilkannya.

CodeQL berjalan sebagai alur kerja khusus .github/workflows/codeql.yml yang menganalisis permukaan Python dan Actions; job security-scan di ci.yml hanya menjalankan bandit, dan menyerahkan publikasi SARIF CodeQL kepada codeql.yml. Lencana keamanan mengonsumsi JSON endpoint yang dipublikasikan oleh alur kerja badges alih-alih lencana alur kerja native GitHub, sehingga lencana tetap stabil terlepas dari topologi pemindai yang mendasarinya.

4. Mekanisme publikasi JSONCopy Anchor Link

JSON endpoint dihasilkan oleh .github/workflows/badges.yml. Alur kerja tersebut:

• Dipicu oleh workflow_run setelah alur kerja ci selesai (dan oleh workflow_dispatch manual untuk publikasi ulang tanpa eksekusi CI).
• Me-resolve tag rilis terbaru dengan git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' pada checkout dengan riwayat penuh (fetch-depth: 0; pada checkout dengan kedalaman 1, tidak ada commit bertag yang dapat dijangkau dan lencana menampilkan unreleased), serta kesimpulan CI induk dari peristiwa workflow_run.
• Menghasilkan setiap JSON melalui jq -n sehingga keluarannya cocok secara ketat dengan skema endpoint shields.io (schemaVersion: 1, ditambah label, message, color).
• Memvalidasi setiap JSON yang dikeluarkan dengan jq -e sebelum diunggah.
• Mengunggah direktori sebagai artefak alur kerja bernama badges.

Penerapan artefak ke apothem.ahmedgad.com/badges/ ditangani oleh .github/workflows/publish-static-site.yml. Selama build situs, alur kerja tersebut mengunduh artefak badges terbaru yang berhasil dan menempatkannya di bawah site/dist/badges/. Jika artefak tidak ada atau telah kedaluwarsa, situs tetap diterapkan dan mencatat artefak lencana yang hilang di log alur kerja alih-alih memublikasikan JSON yang rusak.

5. Protokol pemeliharaanCopy Anchor Link

Tambahkan lencana baru dengan memutuskan bentuknya terlebih dahulu:

• Jika lencana mencerminkan status eksekusi sebuah alur kerja CI, utamakan bentuk native GitHub. URL lencana ditetapkan oleh berkas alur kerja; tidak diperlukan infrastruktur publikasi.
• Jika lencana mencerminkan metrik (hitungan, persentase, string versi, label bergradasi) yang diperbarui seiring waktu, gunakan bentuk endpoint shields.io. Tambahkan langkah pembuatan JSON ke .github/workflows/badges.yml di samping lima langkah yang sudah ada dan tambahkan URL konsumen apothem.ahmedgad.com/badges/<name>.json ke deretan lencana README.
• Jika lencana mencerminkan nilai yang memang jarang berubah (lisensi, target bahasa, mode tata kelola), gunakan bentuk statis shields.io. Dokumentasikan irama perubahannya dalam tabel per lencana di berkas ini saat menambahkan lencana tersebut.

Pensiunkan lencana dengan terlebih dahulu menghapusnya dari README, lalu menghapus langkah pembuatan JSON-nya dari alur kerja badges, lalu menghapus barisnya dari tabel per lencana di atas. Jaga agar penghapusan tetap atomik sehingga README tidak pernah merujuk artefak JSON yang tidak dihasilkan alur kerja.

6. Referensi silangCopy Anchor Link

• Alur kerja CI yang status eksekusinya dicerminkan oleh lencana CI native GitHub: .github/workflows/ci.yml.
• Alur kerja badges yang memublikasikan JSON endpoint: .github/workflows/badges.yml.
• Domain situs statis yang menyajikan JSON tersebut: apothem.ahmedgad.com.
• Referensi skema endpoint shields.io: https://shields.io/badges/endpoint-badge.