Release body is the notes file verbatim; mypy CI gate (#56, #30)

[craigmcchesney]

Closes #56
Closes #30

Plan: plan/tickets/56/plan.md. It covers both tickets, and its closing "Implementation notes" section lists where the implementation departs from it.

#56: the release body is the notes file, verbatim

The ticket's diagnosis was that the release already existed when the workflow ran. That turned out to be wrong (see the plan's Background). What actually happened: the workflow published the full body, and a later gh release edit --notes-file republished the notes file alone. That dropped the verification section the workflow had appended.

This PR removes the appending, so the file and the page are the same content:

• release.yml
  • Stages doc/release-notes/<tag>.md as dist/RELEASE_NOTES.md and publishes it as body_path with nothing added. The assembly step is removed.
  • Drops generate_release_notes. A republish from the file would silently lose GitHub's commit list, so each notes file carries a hand-written Full Changelog link instead.
  • Adds a step after publishing that diffs the live body against the file. A dry run against rel-1.16.0 matched, and a one-line change made it fail.
• .dev/tools/check-release-notes.py (new) checks each notes file:
  • It has a ## Verifying these artifacts section.
  • Its --cert-identity names that file's own tag. A stale tag, copied from the previous release, makes sigstore verify reject every genuine artifact. I confirmed this against the rel-1.16.0 downloads.
  • Each sigstore verify identity command names the wheel, the sdist and SHA256SUMS.
  • It has a **Full Changelog** compare link that ends at the file's own tag and starts at an earlier one.
  • Each run starts with a self-test against known-bad notes, like the cookbook checker's canary, so a rule that stops matching fails loudly.
  • It runs in CI's quality job and again at tag time.
• README.env (new): a reference for the release artifacts and how to verify them, following the Java repos' README.env. Its commands were run successfully against the rel-1.16.0 downloads.
• rel-1.16.0.md: backports the verification section the live page carries, widened to verify all three files (the page's version named the wheel only), plus a README.env pointer and the rel-1.15.0...rel-1.16.0 Full Changelog link. The page is republished from the file after merge (see below).
• CLAUDE.md / README.md: document the new notes-file contract and the rule against hand-editing release pages. The republish command is gh release edit <tag> --notes-file ….

#30: mypy src/ is clean and gated in CI

• [tool.mypy]: the generated gRPC package is excluded, and imports into it are not followed. grpc is allowed to be missing, scoped to that module only. There is no python_version, because numpy's stubs need 3.12 syntax.
• [dev] extra: adds types-PyYAML, types-protobuf and pandas-stubs.
• Type fixes:
  • TimestampInput gets an explicit TypeAlias annotation.
  • timestamp_list() takes a Sequence.
  • MldpClient.annotation / .query are typed X | None.
  • data_frame_image_descriptors() uses a private _image_descriptor() helper that never returns None.
• Cookbook checker: its preamble narrows client.annotation / .query once. I tried disabling union-attr instead, but that also hid misspelled names, and the checker's self-test caught it.
• ci.yml: the quality job adds mypy src/ and the release-notes check, and is renamed "Lint, type-check, and docs". main has no required status checks.
• Deferred to Generate typed Python stubs (.pyi) in generate-python-stubs.yml dp-grpc#158: typed protobuf stubs, after which the gRPC exclusion can be removed and a py.typed marker added.

Verification

• All pass locally:
  • mypy src/ reports Success.
  • The cookbook checker reports OK: 107 snippets.
  • check-release-notes.py passes on the real notes file and fails on a copy with the wrong tag.
  • ruff lint and format are clean.
  • All 725 unit tests pass.
  • The SHA-pin check is clean.
  • The release-notes checker's self-test fails when a rule is deliberately broken, and the checker rejects the previous rel-1.16.0.md (wheel-only verify, no changelog link) and a copy with a stale changelog tag.
• The workflow_dispatch rehearsal of release.yml on this branch passed, covering build and sign (run 36059755066). The publish step and the compare step after it run only on a tag push, so they first run for real at rel-1.17.0. Before that, the compare logic was dry-run against the live rel-1.16.0 body.

After merge

Republish rel-1.16.0 from the updated file, so the page gains the Full Changelog link and the three-file verify command:

gh release edit rel-1.16.0 --notes-file doc/release-notes/rel-1.16.0.md

This PR must merge before the rel-1.17.0 tag is pushed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Bqq8uGF2zNbHW9FU3vfj7Q

[Copilot]

Copilot review overview

🟡 Changes recommended

The missing changelog link and incomplete verification-command enforcement leave release-contract issues unresolved.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 · 1

Open (2)

• Add Full Changelog compare link to release notes · New
• Require verification of wheel, sdist, and SHA256SUMS · New

What changed in this PR

Updates release publishing so notes are verbatim and adds a gated mypy src/ check with supporting documentation and validation tooling.

Changes:

• Reworks release workflow publication and body verification.
• Adds release-note and artifact verification checks.
• Adds mypy configuration, dependencies, and typing fixes.
• Updates CI and project documentation.

File	Description
src/​dp_python_lib/​client/​time_conversions.py	Makes the timestamp union an explicit type alias.
src/​dp_python_lib/​client/​mldp_client.py	Types optional sub-clients accurately.
src/​dp_python_lib/​client/​data_frame.py	Broadens timestamp inputs to Sequence.
src/​dp_python_lib/​client/​data_frame_conversions.py	Adds non-optional image descriptor handling.
README.md	Updates CI and release documentation.
README.env	Documents artifact verification.
pyproject.toml	Adds mypy configuration and typing dependencies.
plan/​tickets/​56/​plan.md	Records design and implementation decisions.
doc/​release-notes/​rel-1.16.0.md	Adds release verification and installation instructions.
CLAUDE.md	Documents release and typing conventions.
.github/​workflows/​release.yml	Publishes notes verbatim and verifies the live body.
.github/​workflows/​ci.yml	Adds mypy and release-note checks.
.dev/​tools/​check-release-notes.py	Validates release-note identity and verification content.
.dev/​tools/​check-cookbook-snippets.py	Narrows optional client types for mypy.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.