Release e versionamento

Regra de versão

O número da versão vive em dois lugares:

  • pyproject.toml

  • src/pynfse_nacional/__init__.py

Os dois precisam bater antes de um release. Se não baterem, a publicação fica confusa e o usuário final percebe na primeira instalação.

Forma de release

O fluxo normal é este:

  1. atualizar versão e changelog

  2. rodar os testes e o lint do que mudou

  3. checar git status --short --branch

  4. confirmar que o tag ainda não existe

  5. rodar uv run release ou uv run release --repository testpypi --dry-run

  6. criar um tag anotado, como v0.5.1

  7. fazer push da branch e do tag

  8. conferir se o pacote e a documentação apareceram no lugar certo

O checklist oficial continua em RELEASE_CHECKLIST.md. Use ele antes de cortar tag. Ele cobre o que normalmente escapa quando a pressa aperta.

Regras para documentação

  • Mudança que afeta comportamento público precisa de ajuste no guia e, se houver API nova, na referência da API.

  • Página de apêndice serve para regras operacionais, não para tutorial longo.

  • Se a alteração mexe em certificado, mTLS, PDF ou release, deixe isso escrito na documentação do mesmo PR.

  • Texto de docs deve ser direto. Se parecer texto de marketing, está longo demais.

CI e publicação

Sim, a CI de documentação já está conectada.

O workflow em .github/workflows/docs.yml:

  • roda em push e pull_request quando mexe em docs/**, src/**, README.md, pyproject.toml ou uv.lock

  • instala as dependências de docs com uv sync --group docs --frozen

  • gera o site com uv run sphinx-build -b html -W --keep-going docs site

  • publica no GitHub Pages quando o push cai na branch master

O que ainda não existe é um workflow separado para publicar pacote no PyPI. Isso continua no comando release e no processo manual descrito acima.

O botão manual workflow_dispatch no workflow de docs só constrói o site. Ele não publica no GitHub Pages, porque o job de deploy roda só em push na branch master.