feat: publication files, drop counts and release workflow (spec 006)

.github/workflows/ci.yml

@@ -40,3 +40,7 @@ jobs:
           for indice in given_names family_names; do
             uv run python -c 'import csv, sys; linhas = list(csv.DictReader(open(sys.argv[1], encoding="utf-8"))); sys.exit(not linhas or not all(l["group_id"] for l in linhas))' "$RUNNER_TEMP/dist-oficiais/$indice.csv"
           done
+      - name: Ensaio da release (spec 006, R7.5)
+        run: |
+          tools/release.sh fixture-cache "$RUNNER_TEMP/cache-release"
+          tools/release.sh build "$(date -u +%Y.%m)" "$RUNNER_TEMP/cache-release" "$RUNNER_TEMP/release"

.github/workflows/release.yml

@@ -0,0 +1,83 @@
+name: Release
+
+# Spec 006, R7, e ADR 0014. Na tag CalVer, monta a release a partir do cache anexado ao rascunho
+# e envia os assets ao rascunho. Nunca publica a release nem cria tag; o disparo manual é ensaio.
+# Actions fixadas por SHA de commit; o comentário diz a tag correspondente.
+on:
+  push:
+    tags:
+      - "[0-9][0-9][0-9][0-9].[0-9][0-9]"
+      - "[0-9][0-9][0-9][0-9].[0-9][0-9].[0-9]*"
+  workflow_dispatch:
+    inputs:
+      release:
+        description: "Nome da release do ensaio (AAAA.MM[.N]); o ensaio usa as amostras de tests/fixtures e não envia nada"
+        required: true
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  ensaio:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    env:
+      RELEASE: ${{ inputs.release }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          enable-cache: true
+      - name: Instalar dependências
+        run: uv sync --locked
+      - name: Conferir o nome da release
+        run: tools/release.sh check "$RELEASE"
+      - name: Cache de ensaio com as amostras
+        run: tools/release.sh fixture-cache "$RUNNER_TEMP/cache"
+      - name: Build offline e verificação
+        run: tools/release.sh build "$RELEASE" "$RUNNER_TEMP/cache" "$RUNNER_TEMP/dist/$RELEASE"
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: ensaio-release
+          path: ${{ runner.temp }}/dist/
+
+  release:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      RELEASE: ${{ github.ref_name }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          enable-cache: false
+      - name: Instalar dependências
+        run: uv sync --locked
+      - name: Conferir o nome da release
+        run: tools/release.sh check "$RELEASE"
+      - name: Cache das fontes anexado ao rascunho
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: tools/release.sh fetch-cache "$RELEASE" "$RUNNER_TEMP/cache"
+      - name: Build offline e verificação
+        run: tools/release.sh build "$RELEASE" "$RUNNER_TEMP/cache" "$RUNNER_TEMP/dist/$RELEASE"
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: release
+          path: ${{ runner.temp }}/dist/
+      - name: Enviar os assets ao rascunho
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: tools/release.sh upload "$RELEASE" "$RUNNER_TEMP/dist/$RELEASE"

.gitignore

@@ -7,10 +7,11 @@ __pycache__/
 output/
 *.tsv
 *.parquet
+# Spec 006, R9: Parquet versionado só em amostras de teste
+!tests/fixtures/**/*.parquet
 *.tar.gz
 credentials.json
 
-
 nohup.out
 *.out
 
@@ -94,7 +95,7 @@ celerybeat-schedule
 .env
 
 # virtualenv
-.venv
+.venv/
 venv/
 ENV/
 
@@ -110,7 +111,6 @@ ENV/
 
 # mypy
 .mypy_cache/
-.venv/
 
 # Cache de downloads das fontes (spec 002, R4)
 /cache/

AGENTS.md

@@ -18,13 +18,14 @@ O contrato do kit é do tools-dataset ([spec 004 de lá](https://github.com/Benc
 uv sync --locked             # instala as dependências do uv.lock
 uv run pytest -q             # testes (nunca usam a rede)
 uv run namescommons --help        # CLI do pipeline
+tools/release.sh build <AAAA.MM> <cache> <saída>   # release local, sem publicar (spec 006)
 ```
 
 A CI também roda o pipeline offline sobre as amostras de `tests/fixtures/`:
 
 ```sh
 PYTHONPATH=tests uv run namescommons run --offline --sources tests/fixtures/sources.yaml \
-  --adapters adaptadores --cache <cache> --out <saida> --release 2026.10
+  --adapters adaptadores --cache <cache> --out <saída> --release 2026.10
 ```
 
 ## Atualizar o kit de fontes
@@ -51,6 +52,27 @@ O INSEE publica cada edição do Fichier des prénoms numa página nova, sem lis
 5. Confira o formato (colunas `sexe;prenom;periode;valeur;rang`, códigos de sexo) e ajuste `tests/test_fr_insee_births.py` e o `README.md` se algo mudou.
 6. Rode `uv run pytest -q`: `tests/test_insee_edicao.py` falha se algum dos lugares acima ficou para trás.
 
+## Publicar uma release
+
+Procedimento da [spec 006](docs/specs/006-publicacao/spec.md) e do [ADR 0014](docs/adr/0014-processo-de-release.md). Só o dono publica; nenhum agente cria tag, rascunho ou release sem aprovação explícita.
+
+1. Escolha o nome em CalVer (`AAAA.MM`, ou `AAAA.MM.N` para mais de uma no mês). Releases são imutáveis: nunca reaproveite um nome.
+2. Confira se a [Statistics Canada Open Licence](https://www.statcan.gc.ca/en/reference/licence) mudou desde a versão "Date modified: 2025-07-10". Se mudou, reavalie o [ADR 0004](docs/adr/0004-licenca-statistics-canada.md) antes de seguir.
+3. Monte o cache completo: `uv run namescommons fetch --refresh`; baixe pelo navegador o ZIP nacional da SSA e o CSV da Nova Zelândia para os caminhos que as mensagens de erro indicam (por cópia, não link simbólico); atualize `retrieved` em `sources.yaml` e faça o commit em `master` por PR.
+4. Ensaie localmente: `tools/release.sh build AAAA.MM cache /tmp/dist/AAAA.MM`. Leia `DATASET_CARD.md` e `ATTRIBUTION.txt` da saída.
+5. Empacote o cache e prepare o rascunho:
+
+   ```sh
+   tar -czf source-cache.tar.gz -C cache .
+   gh release create AAAA.MM --draft --title AAAA.MM --notes "Names Commons Dataset AAAA.MM"
+   gh release upload AAAA.MM source-cache.tar.gz
+   ```
+
+6. Crie e envie a tag assinada no commit de `master` que gera a release: `git tag -s AAAA.MM -m AAAA.MM && git push origin AAAA.MM`. O workflow `Release` baixa o cache do rascunho, roda o build offline, confere `SHA256SUMS`, envia os assets ao rascunho e remove dele `source-cache.tar.gz`.
+7. Revise o rascunho (assets, cartão, atribuições) e publique pelo GitHub. Se o workflow falhar no meio, apague os assets enviados ao rascunho antes de rodar de novo: o envio nunca sobrescreve.
+
+O disparo manual do workflow (`workflow_dispatch`) é só ensaio, sobre as amostras de `tests/fixtures/`.
+
 ## Convenções
 
 - Commits assinados com GPG, autor Matheus Breguêz `<matbrgz@gmail.com>`. Nunca `--no-gpg-sign` nem `--author`.

DATA_LICENSE

@@ -1,3 +1,23 @@
+Names Commons Dataset: data licence
+
+The data published by this project, that is, the release files built by the
+namescommons package from the sources declared in sources.yaml, is licensed
+under the Creative Commons Attribution 4.0 International licence (CC BY 4.0),
+reproduced below. The code is licensed under Apache-2.0 (see LICENSE). The
+contents of legacy/ are not part of the dataset and are not covered by this
+licence.
+
+Attribute the dataset as:
+
+  Names Commons Dataset, release <release>, BenchCommons (https://github.com/BenchCommons/dataset-names), licensed under CC BY 4.0. Upstream sources and notices: see ATTRIBUTION.txt.
+
+Each release carries ATTRIBUTION.txt with the attribution text and licence of
+every upstream source, and the notices some of those licences require (for
+example the Statistics Canada Open Licence). Keep them when you redistribute
+the data.
+
+=======================================================================
+
 Attribution 4.0 International
 
 =======================================================================

README.md

@@ -22,19 +22,39 @@ Originally forked from [Debdut/names.io](https://github.com/Debdut/names.io).
 
 Attribution text for each source is in `sources.yaml`.
 
-## Output layout
+## Releases
 
-A release contains:
+Releases are published on the [GitHub Releases page](https://github.com/BenchCommons/dataset-names/releases), tagged in CalVer (`YYYY.MM`, with `.N` for more than one in a month). Each release contains:
 
 ```
-by_country/<CC>.csv       one file per country (ISO 3166-1 alpha-2)
 given_names.csv           one row per given name, all countries
 family_names.csv          one row per family name, all countries
+given_names.parquet       the same, with typed nested columns
+family_names.parquet
 observations.parquet      the full observation table
-manifest.json             schema version, sources, row counts, SHA-256 of each file
+variant_links.parquet     links between name variants (Wikidata)
+by_country.zip            by_country/<CC>.csv, one file per country (ISO 3166-1 alpha-2)
+manifest.json             schema version, sources, dropped records, row counts and SHA-256 of each table
+DATASET_CARD.md           fields, sources, coverage, suppression, known limitations, licence, how to cite
+ATTRIBUTION.txt           attribution text and licence of every source, and required notices
+DATA_LICENSE              CC BY 4.0, with the dataset's attribution line
+SHA256SUMS                SHA-256 of every asset
 ```
 
-`given_names` and `family_names` are also written as Parquet. Counts of different types (`births`, `population`, `attested`) are never added together. The schema is defined in [spec 001](docs/specs/001-esquema/spec.md).
+Counts of different types (`births`, `population`, `attested`) are never added together. The schema is defined in [spec 001](docs/specs/001-esquema/spec.md); the release files in [spec 006](docs/specs/006-publicacao/spec.md).
+
+Verify a download with `sha256sum -c SHA256SUMS` in the directory with the assets, or with `sha256sum -c --ignore-missing SHA256SUMS` if you downloaded only some of them. Cite a release as written in its `DATASET_CARD.md`:
+
+> Names Commons Dataset, release YYYY.MM, BenchCommons (https://github.com/BenchCommons/dataset-names), licensed under CC BY 4.0. Upstream sources and notices: see ATTRIBUTION.txt.
+
+Keep `ATTRIBUTION.txt` with the data when you redistribute it. The release layout follows the input contract of [tools-dataset](https://github.com/BenchCommons/tools-dataset/blob/main/docs/specs/001-input-contract/spec.md) (`DATA_LICENSE`, `ATTRIBUTION.txt` and `SHA256SUMS` at the top level), so benchmark inputs can be added to the same releases.
+
+Releases are built by the [release workflow](.github/workflows/release.yml) from a source cache attached to a draft release, and published by the maintainer ([ADR 0014](docs/adr/0014-processo-de-release.md)). To build a release locally without publishing anything:
+
+```sh
+tools/release.sh fixture-cache /tmp/cache                     # or a full cache from namescommons fetch
+tools/release.sh build 2026.10 /tmp/cache /tmp/dist/2026.10   # namescommons run --offline + checksum verification
+```
 
 ## Quick start
 
@@ -49,6 +69,8 @@ uv run namescommons build observations.parquet --out dist --release 2026.10
 uv run namescommons run --out dist --release 2026.10       # fetch, ingest and build in sequence
 ```
 
+`build` and `run` write the whole release directory, including the publication files listed above; `--data-license` points to the licence file copied into it (default `DATA_LICENSE`).
+
 Add `--offline` to `ingest` or `run` to use only files already in the cache. Use `--help` on any command for its options.
 
 The SSA server refuses automated downloads (HTTP 403). Download the national data ZIP in a browser and save it where the error message of `fetch` says, then continue with `--offline` ([spec 003, R4](docs/specs/003-fontes-oficiais/spec.md)).

docs/adr/0014-processo-de-release.md

@@ -0,0 +1,30 @@
+# 0014. Release montada por workflow a partir de um rascunho com o cache das fontes
+
+## Status
+
+Aceito (2026-10-12). Spec [006](../specs/006-publicacao/spec.md).
+
+## Contexto
+
+Uma release do dataset é um conjunto de arquivos gerados a partir do cache das fontes (spec 002) e anexados a uma GitHub Release com tag CalVer (spec 001, R5). Duas fontes bloqueiam o download automático: a SSA responde 403 (spec 003, R4) e o catálogo da Nova Zelândia devolve uma página de desafio (spec 003e, R4). O cache completo, portanto, só pode ser montado por uma pessoa com navegador, e um workflow que baixa as fontes sozinho não consegue montar a release.
+
+As opções avaliadas:
+
+1. **Build e envio na máquina do dono** (`namescommons run` e `gh release upload`). Simples, mas o resultado depende do ambiente local, e nada garante que o commit da tag foi o que gerou os arquivos.
+2. **Workflow que baixa as fontes.** Falha na SSA e na Nova Zelândia.
+3. **Workflow que lê o cache de um rascunho de release.** O dono monta o cache, empacota (`source-cache.tar.gz`) e o anexa a um rascunho com o nome da tag. O push da tag dispara o workflow, que baixa o cache do rascunho, roda o build offline no commit da tag, verifica as somas e envia os assets ao rascunho. Rascunhos não são públicos, e a publicação continua um ato do dono.
+4. **Cache como artefato ou cache do Actions.** Não há como o dono enviar um arquivo ao cache do Actions pelo navegador, e artefatos expiram.
+
+## Decisão
+
+- Opção 3. O workflow `.github/workflows/release.yml` roda no push de uma tag CalVer, baixa `source-cache.tar.gz` do rascunho da release com o mesmo nome, roda `tools/release.sh build` (que chama `namescommons run --offline` e verifica `SHA256SUMS`) e envia os assets com `tools/release.sh upload`.
+- O envio nunca usa `--clobber`, recusa release publicada (releases são imutáveis, spec 001 do tools-dataset, R6.2) e remove `source-cache.tar.gz` do rascunho só depois de enviar os assets, para que os arquivos brutos das fontes nunca sejam publicados junto com o dataset.
+- O workflow nunca publica a release nem cria ou move tag. O disparo manual (`workflow_dispatch`) é sempre ensaio, sobre as amostras de `tests/fixtures/`, e a CI roda o mesmo ensaio em todo PR.
+- A lógica fica em `tools/release.sh`, e não no YAML, para ser testada com um `gh` falso e rodada localmente.
+
+## Consequências
+
+- A release é reproduzível a partir do commit da tag e do cache anexado ao rascunho; o cache não fica público.
+- O dono continua tendo de baixar a SSA e a Nova Zelândia pelo navegador antes de cada release, e de revisar o rascunho antes de publicar.
+- Se o envio falhar no meio, o rascunho fica com parte dos assets e com o cache; uma nova execução recusa sobrescrever, e o dono apaga os assets do rascunho antes de repetir.
+- O caminho real (baixar do rascunho e enviar) só é exercitado com o `gh` falso dos testes até a primeira release; o comportamento do `gh` com rascunhos é o documentado pelo GitHub CLI.

docs/adr/0015-legado-congelado.md

@@ -0,0 +1,27 @@
+# 0015. `legacy/` fica no repositório como arquivo histórico congelado
+
+## Status
+
+Aceito (2026-10-12), por decisão do dono do repositório. Spec [006](../specs/006-publicacao/spec.md), R10.
+
+## Contexto
+
+A spec 001 (R6) moveu as listas planas originais (`first_names.all.txt`, `last_names.all.txt`) e os scripts `generate/` para `legacy/`, sem alteração, e deixou para a spec 006 decidir o destino do diretório. São 22 arquivos e 2.091.482 bytes.
+
+O conteúdo de `legacy/` não tem licença declarada: veio de sites, gists e repositórios sem licença, e inclui nomes dos datasets do IMDb, com termos não comerciais (ADR 0001). O dataset novo não o ingere, e o contrato de entradas do tools-dataset (spec 001 de lá, R1.3) o exclui.
+
+As opções eram tirar o diretório da árvore (o conteúdo continuaria no histórico do git) ou mantê-lo congelado. A primeira versão deste ADR propôs a remoção; o dono decidiu manter.
+
+## Decisão
+
+- `legacy/` fica no repositório como arquivo histórico congelado: nenhum arquivo é alterado, acrescentado ou removido.
+- `legacy/` não é ingerido pelo pipeline, não entra em nenhum arquivo das releases e está fora do contrato de entradas do tools-dataset (R1.3 de lá).
+- `legacy/README.md`, o preâmbulo de `DATA_LICENSE` e o README dizem que o diretório não faz parte do dataset e não é coberto por `DATA_LICENSE` nem por `LICENSE`.
+- `tests/test_legacy.py` continua conferindo que as listas estão intactas (spec 001, critério 6).
+
+## Consequências
+
+- Quem usava as listas antigas por caminho no repositório continua encontrando os arquivos.
+- O repositório segue distribuindo, ao lado de `LICENSE` e `DATA_LICENSE`, material sem concessão de licença; o aviso em `legacy/README.md`, no README e em `DATA_LICENSE` é a única barreira contra o uso equivocado.
+- Os 2 MB das listas continuam em clones, buscas e ferramentas de verificação de licença, que podem apontar o diretório.
+- Rever a decisão exige um ADR novo que substitua este.

docs/specs/001-esquema/spec.md

@@ -101,9 +101,11 @@ docs/specs/, docs/adr/
 
 Nota: a release pode incluir `variant_links.parquet` (spec 004, R4.6), contado no `manifest.json`, cuja lista de fontes é a união das fontes das observações e das ligações (spec 005, R7.4). Versões: `1.1.0` (spec 004, R4.7) e `1.2.0` (spec 005, R8).
 
+Nota (spec 006, R2 e R5): o manifesto ganha `data_license` e, por fonte, `name`, `observations` e `dropped`; a release ganha `DATA_LICENSE`, `ATTRIBUTION.txt`, `DATASET_CARD.md`, `by_country.zip` e `SHA256SUMS`, fora de `files`. Versão `1.3.0` ([spec 006](../006-publicacao/spec.md)).
+
 ### R6. Legado
 
-`first_names.all.txt`, `last_names.all.txt` e `generate/` vão para `legacy/` sem alteração de conteúdo e não são ingeridos no dataset novo (ADR 0001). A retirada é decidida na spec 006.
+`first_names.all.txt`, `last_names.all.txt` e `generate/` vão para `legacy/` sem alteração de conteúdo e não são ingeridos no dataset novo (ADR 0001). A retirada é decidida na spec 006. Decisão: [ADR 0015](../../adr/0015-legado-congelado.md) (fica congelado no repositório).
 
 ## Critérios de aceite