Политика бейджей

Этот документ является каноническим справочником по полосе бейджей README и инфраструктуре, которая публикует её динамические источники данных. Каждый бейдж в README проекта разрешается через одну из трёх форм, заданных здесь; новые бейджи, добавляемые в будущем, следуют тем же формам или отклоняются на ревью.

1. ПредпосылкиCopy Anchor Link

Статические URL https://img.shields.io/badge/X-Y-Z никогда не меняются сами по себе, поэтому расходятся с реальным состоянием проекта — бейдж release-vN-blue продолжает показывать vN ещё долго после выхода vN+1. Поэтому политика требует динамических форм для каждого меняющегося значения и оставляет статические бейджи для небольшого набора значений (лицензия, целевая версия Python), которые меняются редко и для которых статическая форма честна.

2. АрхитектураCopy Anchor Link

Четыре формы охватывают каждый бейдж проекта:

1. Нативные для GitHub бейджи статуса рабочего процесса. URL бейджа рабочего процесса имеет вид https://github.com/<owner>/<repo>/actions/workflows/<file>/badge.svg и отражает последний запуск в ветке по умолчанию. GitHub отдаёт бейдж на основе публичных метаданных репозитория.
2. Бейджи эндпоинта shields.io. Бейдж эндпоинта shields.io разрешает URL 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. Бейджи реестра и Scorecard. Бейдж, значение которого вычисляет третья сторона на основе уже имеющихся у неё публичных данных: реестр npm (версия и число загрузок, отрисовываемые shields.io) и API OpenSSF Scorecard. Для них проект ничего не публикует; источником является третья сторона.

Публикация метрик проекта через публичные Gist исключена намеренно. Эндпоинты shields.io на домене, который контролирует проект, — каноническая замена.

3. Спецификация по бейджамCopy Anchor Link

Таблица перечисляет бейджи полосы README по порядку. Последний столбец отмечает бейджи, изображение которых отображается, только пока репозиторий публичен: GitHub отдаёт бейдж рабочего процесса приватного репозитория только вошедшим в систему участникам, а Scorecard сканирует только публичные репозитории.

Цель ссылки каждого бейджа на github.com (релизы, рабочий процесс, файл лицензии, issues) открывается, только пока репозиторий публичен.

Рабочий процесс badges также публикует файлы эндпоинтов coverage.json, security.json, supply-chain.json и docs.json для будущих бейджей; сейчас README их не показывает.

CodeQL выполняется как выделенный рабочий процесс .github/workflows/codeql.yml, который анализирует поверхности Python и Actions; задание security-scan в ci.yml запускает только bandit, оставляя публикацию SARIF от CodeQL рабочему процессу codeql.yml. Бейдж безопасности использует JSON эндпоинта, публикуемый рабочим процессом badges, а не нативный для GitHub бейдж рабочего процесса, благодаря чему бейдж остаётся стабильным независимо от топологии нижележащих сканеров.

4. Механизм публикации JSONCopy Anchor Link

JSON эндпоинтов создаёт .github/workflows/badges.yml. Рабочий процесс:

• Запускается по 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.

Развёртыванием артефактов в apothem.ahmedgad.com/badges/ занимается .github/workflows/publish-static-site.yml. Во время сборки сайта этот рабочий процесс скачивает последний успешный артефакт badges и размещает его под site/dist/badges/. Если артефакт отсутствует или истёк, сайт всё равно развёртывается и фиксирует отсутствие артефакта бейджей в журналах рабочего процесса вместо публикации сломанного JSON.

5. Протокол сопровожденияCopy Anchor Link

Добавляя новый бейдж, сначала определите форму:

• Если бейдж отражает состояние выполнения рабочего процесса CI, предпочтите нативную для GitHub форму. URL бейджа задаётся файлом рабочего процесса; инфраструктура публикации не нужна.
• Если бейдж отражает метрику (количество, процент, строку версии, оценочную метку), которая со временем обновляется, используйте форму эндпоинта shields.io. Добавьте шаг генерации JSON в .github/workflows/badges.yml рядом с существующими пятью и добавьте потребительский URL apothem.ahmedgad.com/badges/<name>.json в полосу бейджей README.
• Если бейдж отражает значение, которое действительно меняется редко (лицензия, целевой язык, режим управления), используйте статическую форму shields.io. При добавлении бейджа задокументируйте частоту изменений в таблице по бейджам в этом файле.

Удаляя бейдж, сначала уберите его из README, затем удалите его шаг генерации JSON из рабочего процесса badges, затем удалите его строку из таблицы по бейджам выше. Выполняйте удаление атомарно, чтобы README никогда не ссылался на JSON-артефакт, который рабочий процесс не создаёт.

6. Перекрёстные ссылкиCopy Anchor Link

• Рабочий процесс CI, состояние выполнения которого отражает нативный для GitHub бейдж CI: .github/workflows/ci.yml.
• Рабочий процесс badges, который публикует JSON эндпоинтов: .github/workflows/badges.yml.
• Домен статического сайта, который отдаёт JSON: apothem.ahmedgad.com.
• Справочник по схеме эндпоинта shields.io: https://shields.io/badges/endpoint-badge.