Padronização de CHANGELOG.md¶
Todo pacote de dados publicável do ecossistema mantém um CHANGELOG.md na raiz
do seu repositório. É a fonte de verdade por pacote sobre o que mudou em cada
versão — o changelog do site é apenas o resumo cross-pacote dos
marcos maiores, não substitui os arquivos por repo.
Esta norma define o formato único adotado por todos eles. Complementa a norma de Publicação e Release (que trata do fluxo de tag → PyPI) e a de Padrões de Escrita (que trata do README).
1. Escopo — quem precisa de um CHANGELOG.md¶
Obrigatório em todo pacote versionado por SemVer
e distribuído como biblioteca — os fetchers, os motores SQL (*-sql) e as fundações
(quantilica-core, quantilica-analytics, quantilica-cli, quantilica-catalog).
Ou seja: se o repositório tem [project] version no pyproject.toml e é (ou será)
instalável, ele tem um CHANGELOG.md.
Isento:
- Catálogos de ETL (
sidra-pipelines,bcb-sgs-pipelines) — não têmversionnem API; suas mudanças são as dos arquivosfetch.toml/transform.sql, rastreadas pelo git. - Repositórios de artefato de dados (ex.:
datasus-metadata) — versionam dados gerados, não código de API. - Aplicações web que não são publicadas como biblioteca — não seguem esta norma.
2. Cabeçalho padrão¶
Todo CHANGELOG.md começa exatamente com este cabeçalho (idioma pt-BR, links
para as versões pt-BR das especificações):
# Changelog
Todas as mudanças notáveis deste projeto serão documentadas neste arquivo.
O formato segue [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/),
e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
3. Entradas de versão¶
- Uma entrada por versão, com o título
## [x.y.z] - AAAA-MM-DD(data ISO 8601 da publicação da tag). - Ordem decrescente: a versão mais recente no topo, logo abaixo do cabeçalho.
- A versão do título casa com
[project] versiondopyproject.tomle com a tagvX.Y.Zque dispara o release. - Um parágrafo de contexto opcional pode preceder as categorias, quando a versão precisa de uma explicação de fundo (ex.: primeiro release no PyPI, quebra de compatibilidade). Mantenha-o curto.
Mudanças ainda não lançadas ficam sob ## [Não lançado] no topo; ao publicar,
renomeie o bloco para ## [x.y.z] - AAAA-MM-DD.
4. Categorias permitidas¶
Apenas as seis categorias do Keep a Changelog, como ### dentro de cada versão,
nesta grafia pt-BR e só as que se aplicam (não crie seções vazias):
| Seção | Quando usar |
|---|---|
### Adicionado |
Novas funcionalidades, comandos, módulos ou APIs. |
### Alterado |
Mudanças em comportamento, dependências ou API existente. |
### Descontinuado |
Funcionalidade ainda presente, mas marcada para remoção. |
### Removido |
Funcionalidade/código removidos nesta versão. |
### Corrigido |
Correções de bug (inclui hardening e robustez). |
### Segurança |
Correções de vulnerabilidade. |
Não invente categorias (### Melhorado, ### Notas, ### Robustez, …) — a única
seção adicional permitida é ### Histórico anterior, no bootstrap de repos com
tags antigas (§7). Uma observação que não é uma mudança catalogável vai como
blockquote ao final da entrada:
> **Nota:** a 0.7.2 foi publicada declarando `quantilica-core[cli]` por engano;
> a 0.7.3 corrige para `quantilica-core`.
5. Como escrever cada item¶
Seguindo a norma de escrita:
- Idioma: prosa em português; identificadores, nomes de função, flags de CLI e
nomes de pacote em inglês, sempre em
código. - Altitude: descreva o efeito para quem usa o pacote, não o diff. "Corrige X que
quebrava com
AttributeError" é melhor que "mudarow.series_name". - Concisão: uma linha por mudança sempre que possível; quebre em ~88 colunas
para casar com o
line-lengthdo repo. - Sem emoji decorativo (idem README).
5.1 O que um changelog nunca cita¶
O CHANGELOG.md descreve o que mudou para quem usa o pacote — comportamento,
API, dependências, formatos de arquivo, fontes de dados. Ele mora num repositório
público e fica no histórico para sempre, inclusive depois de editado. Por isso
nunca cita:
| Categoria | Exemplos do que não escrever | Escreva em vez disso |
|---|---|---|
| Planos e fases de trabalho | "Onda 3A", "Fase 2 do plano AAAA-MM-DD-nome", nomes de arquivos de planejamento |
A mudança em si: "reader.write_parquet delega ao to_parquet do quantilica-analytics" |
| Decisões internas | "ADR de distribuição", "decisão AAAA-MM-DD-nome" |
O efeito: "a URL do índice mudou para https://index.quantilica.com/simple/" |
| Repositórios e serviços privados | Nome de qualquer repositório, aplicação ou plugin que não seja público; "consumidores internos" | Descreva o contrato: "quem guarda contas pelo código passa a ver 10 no lugar de 1.0" |
| Infraestrutura e operação | Agendadores, horários de execução, servidores, ambientes de ingestão, filas, armazenamento interno, "o cron falhou" | O sintoma público: "centenas de respostas 404", "o servidor derruba a conexão a cada ~4 MB" |
| Ferramentas e processo de desenvolvimento | Arquivos de agentes de IA, "workspace" privado de desenvolvimento, auditorias e relatórios internos | Omita. Se não muda nada para quem usa o pacote, não é entrada de changelog |
| Credenciais e caminhos | Tokens, hosts, IPs, e-mails, caminhos de máquina | Nunca, em nenhuma circunstância |
Teste prático antes de commitar: "alguém que só vê o GitHub e o PyPI entenderia essa linha e conseguiria agir sobre ela?" Se a frase só faz sentido para quem tem acesso a um repositório privado, ela não entra — mesmo que seja verdadeira.
A mesma regra vale para README e para as mensagens de commit: o histórico git é público e permanente, e reescrevê-lo depois exige force-push.
Verificação automática. Todo repositório público tem o workflow
.github/workflows/public-hygiene.yml, com a mesma lógica em todos eles. Ele roda em
push, em pull_request e sob demanda, e falha o CI quando encontra termos
internos em CHANGELOG.md, README* e docs/changelog.md — e, nos PRs, nas
mensagens dos commits. A lista de termos não é pública: listá-la num
repositório público revelaria justamente o que ela protege. Ela vive num segredo
de organização do GitHub (HYGIENE_TERMS), lido pelo workflow, e a fonte
editável fica em arquivo privado da skill quantilica-ci. Para alterá-la, edite
esse arquivo e republique o segredo com driver.py hygiene-secret; nenhum
repositório precisa de commit. Em PRs de forks o segredo não existe: o job avisa
e passa, e a verificação roda quando o mantenedor integra. Falso positivo
legítimo: termine a linha com
<!-- hygiene-ok -->. O workflow é uma rede de segurança, não um substituto
para o teste prático acima: ele só conhece os termos que já vazaram.
6. Relação com SemVer, tags e o changelog do site¶
- O tipo de alteração define o bump SemVer de acordo com a Política Canônica de Versionamento:
Corrigido,Segurançaou melhorias internas \(\to\)PATCH(x.y.Z).Adicionado, novos endpoints/tabelas ouDescontinuado\(\to\)MINOR(x.Y.0).Removidoou quebra de contrato de API emAlterado\(\to\)MAJOR(X.0.0).- A tag
vX.Y.Zé o release (disparapublish.yml); oCHANGELOG.mddeve conter a entrada dessa versão antes de criar a tag. - Isolamento de Commit: O
CHANGELOG.mde opyproject.tomlsão commitados juntos em um commit exclusivo de release (release: vX.Y.Z), separado dos commits de implementação (feat,fix). - Marcos maiores (novo pacote, publicação no PyPI, renomeação) também entram, de forma resumida e cross-pacote, no changelog do site. O detalhe fica sempre no
CHANGELOG.mddo repo.
7. Bootstrap de repositórios com histórico¶
Ao adotar o changelog num repo que já tem várias tags de release, não reconstrua
o histórico linha a linha (risco de inventar mudanças). A primeira entrada documenta
o estado atual do pacote e uma seção ### Histórico anterior remete às tags:
## [3.0.0] - 2026-05-19
Primeira entrada em formato Keep a Changelog; documenta o estado do pacote nesta
versão.
### Adicionado
- ...
### Histórico anterior
Versões até a 3.0.0 antecedem a adoção deste changelog e estão registradas nas tags
do repositório: 2.1.1 (2026-02-09), 2.0.0 (2026-01-31), 1.0.0 (2025-12-31), …
A partir daí, cada release ganha sua entrada normalmente.
8. Exemplo completo¶
# Changelog
Todas as mudanças notáveis deste projeto serão documentadas neste arquivo.
O formato segue [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/),
e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
## [1.3.1] - 2026-07-22
### Corrigido
- `Config.__str__` não expõe mais a senha do banco em texto puro (mascarada como `***`).
### Removido
- Código morto sem chamadores: `build_localidade_lookup`, `Storage.read_data_dir`.
## [1.3.0] - 2026-07-16
### Adicionado
- Primeiro release público no PyPI.
9. Checklist¶
[ ] CHANGELOG.md na raiz, com o cabeçalho padrão (§2)
[ ] entrada da nova versão no topo: ## [x.y.z] - AAAA-MM-DD (§3)
[ ] só as categorias de §4, sem seções vazias nem inventadas
[ ] versão casa com pyproject.toml e com a tag vX.Y.Z
[ ] nenhuma entrada cita planos, decisões, repositórios privados ou infraestrutura (§5.1)
[ ] README aponta para o CHANGELOG.md (ver norma de escrita)
[ ] entrada escrita antes de criar a tag de release