Política de selos

Este documento é a referência canônica para a faixa de selos do README e para a infraestrutura que publica suas fontes de dados dinâmicas. Todo selo no README do projeto é resolvido por meio de uma das três formas especificadas aqui; os novos selos adicionados no futuro seguem as mesmas formas ou são rejeitados na revisão.

1. ContextoCopy Anchor Link

URLs estáticas https://img.shields.io/badge/X-Y-Z nunca mudam por conta própria, então se distanciam do estado real do projeto — um selo release-vN-blue continua mostrando vN muito depois de vN+1 ser lançado. Por isso, a política exige formas dinâmicas para todo valor que muda e reserva os selos estáticos para o pequeno conjunto de valores (licença, versão alvo do Python) que raramente mudam, nos quais a forma estática é honesta.

2. ArquiteturaCopy Anchor Link

Quatro formas cobrem todos os selos do projeto:

1. Selos de status de fluxo de trabalho nativos do GitHub. A URL do selo de um fluxo de trabalho tem a forma https://github.com/<owner>/<repo>/actions/workflows/<file>/badge.svg e reflete a execução mais recente na branch padrão. O GitHub serve o selo a partir dos metadados públicos do repositório.
2. Selos de endpoint do shields.io. Um selo de endpoint do shields.io resolve uma URL https://img.shields.io/endpoint?url=<published-json> na qual o JSON segue o schema de endpoint do shields.io (schemaVersion, label, message, color). O JSON publicado fica em apothem.ahmedgad.com/badges/*.json; seu conteúdo é gerado por um fluxo de trabalho de CI a cada execução bem-sucedida do CI. Os selos de endpoint mantêm as métricas sob publicação controlada pelo projeto, e não em um armazenamento mutável de terceiros.
3. Selos estáticos do shields.io. Um selo estático tem a forma https://img.shields.io/badge/<label>-<message>-<color>, sem fonte de dados reativa. Reservados para valores que de fato raramente mudam (identificador de licença, versão alvo do Python).
4. Selos de registro e de scorecard. Um selo cujo valor um terceiro calcula a partir de dados públicos que ele já detém: o registro do npm (versão e downloads, renderizados pelo shields.io) e a API do OpenSSF Scorecard. O projeto não publica nada para esses selos; o terceiro é a fonte.

A publicação de métricas do projeto em Gists públicos é excluída por design. Os endpoints do shields.io sobre o domínio controlado pelo projeto são o substituto canônico.

3. Especificação por seloCopy Anchor Link

A tabela lista a faixa de selos do README em ordem. A última coluna marca os selos cuja imagem só é renderizada enquanto o repositório é público: o GitHub serve o selo de fluxo de trabalho de um repositório privado apenas a membros autenticados, e o Scorecard analisa somente repositórios públicos.

O destino do link de cada selo em github.com (os lançamentos, o fluxo de trabalho, o arquivo de licença, as issues) só abre enquanto o repositório é público.

O fluxo de trabalho de selos também publica os arquivos de endpoint coverage.json, security.json, supply-chain.json e docs.json para selos futuros; o README não os exibe hoje.

O CodeQL é executado como um fluxo de trabalho dedicado, .github/workflows/codeql.yml, que analisa as superfícies de Python e de Actions; o job security-scan do ci.yml executa apenas o bandit, deixando a publicação do SARIF do CodeQL para o codeql.yml. O selo de segurança consome o JSON de endpoint publicado pelo fluxo de trabalho de selos em vez de um selo de fluxo de trabalho nativo do GitHub, o que mantém o selo estável independentemente da topologia de scanners subjacente.

4. Mecanismo de publicação dos JSONsCopy Anchor Link

Os JSONs de endpoint são produzidos por .github/workflows/badges.yml. O fluxo de trabalho:

• É disparado por workflow_run depois que o fluxo de trabalho ci termina (e por workflow_dispatch manual, para republicar sem uma execução do CI).
• Resolve a tag de lançamento mais recente com git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' em um checkout com o histórico completo (fetch-depth: 0; em um checkout de profundidade 1, nenhum commit com tag é alcançável e o selo mostra unreleased), e a conclusão do CI pai a partir do evento workflow_run.
• Gera cada JSON via jq -n, para que a saída corresponda estritamente ao schema de endpoint do shields.io (schemaVersion: 1, mais label, message, color).
• Valida cada JSON emitido com jq -e antes do upload.
• Faz o upload do diretório como um artefato de fluxo de trabalho chamado badges.

A implantação dos artefatos em apothem.ahmedgad.com/badges/ fica a cargo de .github/workflows/publish-static-site.yml. Durante o build do site, esse fluxo de trabalho baixa o artefato badges bem-sucedido mais recente e o prepara em site/dist/badges/. Se o artefato estiver ausente ou expirado, o site ainda é implantado e registra o artefato de selos ausente nos logs do fluxo de trabalho, em vez de publicar um JSON quebrado.

5. Protocolo de manutençãoCopy Anchor Link

Para adicionar um novo selo, decida primeiro a forma:

• Se o selo reflete o estado de execução de um fluxo de trabalho de CI, prefira a forma nativa do GitHub. A URL do selo é fixada pelo arquivo do fluxo de trabalho; nenhuma infraestrutura de publicação é necessária.
• Se o selo reflete uma métrica (uma contagem, uma porcentagem, uma string de versão, um rótulo graduado) que se atualiza ao longo do tempo, use a forma de endpoint do shields.io. Adicione uma etapa de geração de JSON a .github/workflows/badges.yml ao lado das cinco existentes e adicione a URL consumidora apothem.ahmedgad.com/badges/<name>.json à faixa de selos do README.
• Se o selo reflete um valor que de fato raramente muda (licença, linguagem alvo, modo de governança), use a forma estática do shields.io. Documente a cadência de mudança na tabela por selo deste arquivo ao adicionar o selo.

Para aposentar um selo, remova-o primeiro do README, depois remova sua etapa de geração de JSON do fluxo de trabalho de selos e, por fim, remova sua linha da tabela por selo acima. Mantenha a exclusão atômica, para que o README nunca faça referência a um artefato JSON que o fluxo de trabalho não produz.

6. Referências cruzadasCopy Anchor Link

• O fluxo de trabalho de CI cujo estado de execução o selo de CI nativo do GitHub reflete: .github/workflows/ci.yml.
• O fluxo de trabalho de selos que publica os JSONs de endpoint: .github/workflows/badges.yml.
• O domínio do site estático que serve os JSONs: apothem.ahmedgad.com.
• A referência do schema de endpoint do shields.io: https://shields.io/badges/endpoint-badge.