Политика бейджей
Задаёт источники динамических и статических бейджей для README, охватывая нативный для GitHub статус рабочего процесса, JSON эндпоинта shields.io и статические формы бейджей.
Этот документ является каноническим справочником для полосы бейджей README и инфраструктуры, которая публикует её динамические источники данных. Каждый бейдж в README проекта разрешается через одну из трёх форм, указанных здесь; новые бейджи, добавляемые в будущем, следуют тем же формам или отклоняются при ревью.
1. Предпосылки
Статические URL https://img.shields.io/badge/X-Y-Z никогда не меняются сами
по себе, поэтому они расходятся с реальным состоянием проекта — бейдж
release-vN-blue продолжает показывать vN ещё долго после выпуска vN+1.
Поэтому политика требует динамических форм для каждого изменяющегося значения и
резервирует статические бейджи для небольшого набора значений (лицензия,
целевая версия Python), которые редко меняются, где статическая форма честна.
2. Архитектура
Три формы охватывают каждый бейдж проекта:
- Нативные для GitHub бейджи статуса рабочего процесса. URL бейджа
рабочего процесса имеет форму
https://github.com/<owner>/<repo>/actions/workflows/<file>/badge.svgи отражает последний запуск в ветке по умолчанию. GitHub отдаёт бейдж из публичных метаданных репозитория. - Бейджи эндпоинта 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. Бейджи эндпоинта удерживают метрики под публикацией, контролируемой проектом, а не в изменяемом стороннем хранилище. - Статические бейджи shields.io. Статический бейдж имеет форму
https://img.shields.io/badge/<label>-<message>-<color>без реактивного источника данных. Зарезервирован для значений, которые действительно редко меняются (идентификатор лицензии, целевая версия Python).
Публикация метрик проекта через публичные Gist исключена по замыслу. Эндпоинты shields.io на контролируемом проектом домене являются каноническим заместителем.
3. Спецификация по бейджам
| Бейдж | Форма | Источник | Форма URL |
|---|---|---|---|
| Статус 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, оставляя публикацию SARIF 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 форму. URL бейджа фиксируется файлом рабочего процесса; инфраструктура публикации не нужна.
- Если бейдж отражает метрику (количество, процент, строку версии, оценочную
метку), которая обновляется со временем, используйте форму эндпоинта
shields.io. Добавьте шаг генерации JSON в
.github/workflows/badges.ymlрядом с существующими пятью и добавьте потребительский URLapothem.ahmedgad.com/badges/<name>.jsonв полосу бейджей README. - Если бейдж отражает значение, которое действительно редко меняется (лицензия, цель языка, режим управления), используйте статическую форму shields.io. Задокументируйте частоту изменений в таблице по бейджам в этом файле при добавлении бейджа.
Выведите бейдж из эксплуатации, сначала удалив его из README, затем удалив его шаг генерации JSON из рабочего процесса badges, затем удалив его строку из таблицы по бейджам выше. Сохраняйте удаление атомарным, чтобы README никогда не ссылался на артефакт JSON, который рабочий процесс не создаёт.
6. Перекрёстные ссылки
- Рабочий процесс 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.