Política de insignias

Este documento es la referencia canónica de la franja de insignias del README y de la infraestructura que publica sus fuentes de datos dinámicas. Cada insignia del README del proyecto se resuelve mediante una de las tres formas especificadas aquí; las insignias nuevas que se agreguen en el futuro siguen las mismas formas o se rechazan en la revisión.

1. AntecedentesCopy Anchor Link

Las URL estáticas https://img.shields.io/badge/X-Y-Z nunca cambian por sí solas, por lo que se alejan del estado real del proyecto: una insignia release-vN-blue sigue mostrando vN mucho después de que se publique vN+1. Por eso la política exige formas dinámicas para cada valor que cambia y reserva las insignias estáticas para el pequeño conjunto de valores (licencia, versión objetivo de Python) que rara vez cambian, donde la forma estática es honesta.

2. ArquitecturaCopy Anchor Link

Cuatro formas cubren cada insignia del proyecto:

1. Insignias de estado de flujo de trabajo nativas de GitHub. La URL de la insignia de un flujo de trabajo tiene la forma https://github.com/<owner>/<repo>/actions/workflows/<file>/badge.svg y refleja la ejecución más reciente en la rama predeterminada. GitHub sirve la insignia a partir de los metadatos públicos del repositorio.
2. Insignias de endpoint de shields.io. Una insignia de endpoint de shields.io resuelve una URL https://img.shields.io/endpoint?url=<published-json> cuyo JSON se ajusta al esquema de endpoint de shields.io (schemaVersion, label, message, color). El JSON publicado reside en apothem.ahmedgad.com/badges/*.json; su contenido lo genera un flujo de trabajo de CI en cada ejecución de CI correcta. Las insignias de endpoint mantienen las métricas bajo una publicación controlada por el proyecto en lugar de un almacén mutable de terceros.
3. Insignias estáticas de shields.io. Una insignia estática tiene la forma https://img.shields.io/badge/<label>-<message>-<color> sin ninguna fuente de datos reactiva. Se reservan para valores que realmente rara vez cambian (identificador de licencia, versión objetivo de Python).
4. Insignias de registro y de scorecard. Una insignia cuyo valor calcula un tercero a partir de datos públicos que ya tiene: el registro de npm (versión y descargas, renderizadas por shields.io) y la API de OpenSSF Scorecard. El proyecto no publica nada para estas; el tercero es la fuente.

La publicación de métricas del proyecto en Gists públicos queda excluida por diseño. Los endpoints de shields.io sobre el dominio controlado por el proyecto son el sustituto canónico.

3. Especificación por insigniaCopy Anchor Link

La tabla lista la franja de insignias del README en orden. La última columna marca las insignias cuya imagen solo se renderiza mientras el repositorio es público: GitHub sirve la insignia de un flujo de trabajo de un repositorio privado solo a los miembros que han iniciado sesión, y Scorecard solo analiza repositorios públicos.

El destino del enlace de cada insignia en github.com (los lanzamientos, el flujo de trabajo, el archivo de licencia, los issues) solo se abre mientras el repositorio es público.

El flujo de trabajo de insignias también publica los archivos de endpoint coverage.json, security.json, supply-chain.json y docs.json para insignias futuras; el README no los muestra hoy.

CodeQL se ejecuta como un flujo de trabajo dedicado, .github/workflows/codeql.yml, que analiza las superficies de Python y de Actions; el trabajo security-scan de ci.yml solo ejecuta bandit y deja la publicación de SARIF de CodeQL a codeql.yml. La insignia de seguridad consume el JSON de endpoint publicado por el flujo de trabajo de insignias en lugar de una insignia de flujo de trabajo nativa de GitHub, lo que mantiene la insignia estable sea cual sea la topología de escáneres subyacente.

4. Mecanismo de publicación de JSONCopy Anchor Link

Los JSON de endpoint los produce .github/workflows/badges.yml. El flujo de trabajo:

• Se dispara con workflow_run después de que se completa el flujo de trabajo ci (y con workflow_dispatch manual para volver a publicar sin una ejecución de CI).
• Resuelve la etiqueta de lanzamiento más reciente con git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' en un checkout con el historial completo (fetch-depth: 0; en un checkout de profundidad 1 no se puede alcanzar ningún commit etiquetado y la insignia muestra unreleased), y la conclusión de la CI padre a partir del evento workflow_run.
• Genera cada JSON mediante jq -n para que la salida se ajuste estrictamente al esquema de endpoint de shields.io (schemaVersion: 1, más label, message, color).
• Valida cada JSON emitido con jq -e antes de subirlo.
• Sube el directorio como un artefacto de flujo de trabajo llamado badges.

Del despliegue de los artefactos en apothem.ahmedgad.com/badges/ se encarga .github/workflows/publish-static-site.yml. Durante la compilación del sitio, ese flujo de trabajo descarga el artefacto badges correcto más reciente y lo coloca bajo site/dist/badges/. Si el artefacto no existe o ha caducado, el sitio se despliega igualmente y registra la falta del artefacto de insignias en los registros del flujo de trabajo en lugar de publicar un JSON roto.

5. Protocolo de mantenimientoCopy Anchor Link

Para agregar una insignia nueva, decide primero su forma:

• Si la insignia refleja el estado de ejecución de un flujo de trabajo de CI, prefiere la forma nativa de GitHub. El archivo del flujo de trabajo fija la URL de la insignia; no se necesita ninguna infraestructura de publicación.
• Si la insignia refleja una métrica (un recuento, un porcentaje, una cadena de versión, una etiqueta graduada) que se actualiza con el tiempo, usa la forma de endpoint de shields.io. Agrega un paso de generación de JSON a .github/workflows/badges.yml junto a los cinco existentes y agrega la URL consumidora apothem.ahmedgad.com/badges/<name>.json a la franja de insignias del README.
• Si la insignia refleja un valor que realmente rara vez cambia (licencia, lenguaje objetivo, modo de gobernanza), usa la forma estática de shields.io. Documenta la cadencia de cambio en la tabla por insignia de este archivo al agregar la insignia.

Para retirar una insignia, elimínala primero del README, luego elimina su paso de generación de JSON del flujo de trabajo de insignias y después elimina su fila de la tabla por insignia de arriba. Mantén la eliminación atómica para que el README nunca haga referencia a un artefacto JSON que el flujo de trabajo no produce.

6. Referencias cruzadasCopy Anchor Link

• El flujo de trabajo de CI cuyo estado de ejecución refleja la insignia de CI nativa de GitHub: .github/workflows/ci.yml.
• El flujo de trabajo de insignias que publica los JSON de endpoint: .github/workflows/badges.yml.
• El dominio del sitio estático que sirve los JSON: apothem.ahmedgad.com.
• La referencia del esquema de endpoint de shields.io: https://shields.io/badges/endpoint-badge.