[aandresalvarez]

📝 Pull Request

Summary

Adds the public STARR-OMOP Release Notes page and a release-driven delivery contract: write the user note with the code change, collect it when the dataset is available, and render committed content at site build. The existing collapsible year/month layout, search, deep links, keyboard controls, compact headings, and responsive tables are retained.

Latest update for review:

• Versioned starr-user-note blocks replace reconstruction from mutable PR descriptions and separate Docs tags. Source reads use explicit Git commits and recover folded/deleted changelog fragments.
• An availability record accounts for included or omitted changes and identifies the dataset suffix, available variants, deployed revision, and entry checksum. Drafts, unresolved decisions, invalid content, and inconsistent imports fail explicitly.
• Idempotent bundle imports feed both Release Notes and Released Datasets from the same catalog. Historical corrections require the next revision and an explanation.
• Docker-only preview/build commands and a Documentation workflow separate credential-free PR verification from credentialed production rendering and Pages deployment.
• The latest review findings are addressed: identifier detection spans Markdown wrapping, inline formatting, and table cells while retaining source locations; entries require an unfenced ### change heading; duplicate IDs are checked across titles, summaries, and bodies. LLM output also preserves lab comparison operators and is generated without trailing whitespace.

Release content: September's existing entry is unchanged. January, June, and September have explicitly marked legacy availability records; unknown provenance is left null, and January/June do not invent historical notes. The October 15 sample is not an available dataset and is deliberately excluded from the production catalog and generated site.

Activation is separate from this PR: the upstream authoring/delivery integration must land after the shared tooling is on this repository's main. GitHub App configuration, Pages/GitHub environment settings, and Google Workload Identity are still required. No upstream workflow, secret, repository setting, or production deployment has been activated by this update. See Automation Activation.

Type of Change

• 📄 New page or FAQ entry
• 📰 Release notes entry (docs/release_notes/*.qmd) or dataset record (data/releases/*.json)
• ✏️ Content update to an existing page or FAQ
• 🛠️ Generator/script change (scripts/*.py)
• 🗂️ Data model regeneration (omop_data_model.qmd inputs)
• 🎨 Styling / theme / navigation change
• 🔧 Build or dev-container configuration
• 📦 Dependency update
• 🐛 Fix (broken link, typo, render error, etc.)

Related Issues

• Related to STAR-12576.

Pages / Files Changed

• Release tooling: scripts/release_catalog.py, scripts/release_pipeline.py, scripts/build_site.py, scripts/generate_release_notes.py.
• Existing generator integration: scripts/generate_docs.py, scripts/generate_llms_txt.py.
• Availability catalog: data/releases/2026-01-18.json, data/releases/2026-06-08.json, data/releases/2026-09-10.json.
• Public content and generated indexes: docs/release_notes/2026-09-10.qmd, docs/release_notes.qmd, docs/released_datasets.qmd, docs/llms.txt, docs/llms-full.txt.
• Navigation and presentation: docs/_quarto.yml, docs/about.qmd, docs/assets/release-notes.js, docs/styles.css.
• Docker/CI: Dockerfile.site, .dockerignore, docker/nginx-preview.conf, .github/workflows/site.yml.
• Regression coverage: tests/test_release_notes.py, tests/test_release_pipeline.py, tests/test_llms_plaintext.py.
• Contributor guidance: README.md, CONTRIBUTING.md, docs/release_notes/README.md, docs/release_notes/_template.qmd, .github/pull_request_template.md, and the build-reproducibility comment in pyproject.toml.

How to Verify

• Ran quarto preview locally and the site renders without errors
• Affected pages display and navigate correctly
• I did not hand-edit generated files (omop_data_model.qmd, faq.qmd, release_notes.qmd, released_datasets.qmd, llms.txt, llms-full.txt)

The quarto preview box is deliberately unchecked: this update was rendered with python scripts/build_site.py --offline and served through Docker/nginx, not by running Quarto on the host. The README's Docker commands reproduce that preview. Open /about/release_notes.html and /about/released_datasets.html; September should appear, October should not, and the dataset link should open September's notes.

The following commands ran inside the starr-docs-omop-site:release-automation Docker image, against the updated working tree:

Command	Result
for test in tests/test_*.py; do python "$test"; done	Passed: 91 tests across six modules, including 35 release-note and 31 release-pipeline tests.
python scripts/release_pipeline.py check-history --base 4139258b823dfbe51b98656c7f0876d8f733041a	Passed against the current PR base.
python scripts/generate_release_notes.py --check	Passed: one published entry backed by the three-record availability catalog.
python scripts/build_site.py --offline	Passed: all 10 configured pages rendered; the preview also includes the generated index page.
git diff --name-only --diff-filter=ACMR -z origin/main | xargs -0 pre-commit run --files	Passed on all PR files after fixing the source generator; whitespace, YAML, conflict, Python debug, Ruff lint, and Ruff format hooks passed. SQL hooks had no applicable files.

Workflow validation:

docker run --rm --network none -v "$PWD:/repo:ro" -w /repo \
  rhysd/actionlint:1.7.7 .github/workflows/site.yml

Result: passed.

Remote CI for 38e5eb2 also passed: Verify documentation and CodeQL. The production publication job was skipped as intended for a pull request.

The Docker-served preview was also exercised in Chromium, Firefox, and WebKit at 1280px and 390px, covering release-only content, expand/collapse, keyboard activation, deep links, compact headings, horizontal overflow, dataset cross-links, and the no-JavaScript fallback. A static check passed for 1,599 internal links/anchors across 11 rendered HTML pages. Generated files match their source generators, and every September table row survives in llms-full.txt.

Not run: credentialed production rendering, live BigQuery FAQ execution, upstream cross-repository delivery, and Pages deployment. Those require the activation settings described above; a passing offline preview is not evidence of production deployment.

Screenshots

No new screenshots attached. This follow-up retains the existing release-page layout; CI uploads a documentation-preview artifact after successful verification.

Checklist

• My commits follow the Conventional Commits format (see CONTRIBUTING.md)
• I previewed the site locally and confirmed everything renders
• Generated files were left untouched (they are produced by the pre-render hooks)
• All internal links and anchors resolve
• pre-commit was run locally prior to submission

[Copilot]

Copilot review overview

🟡 Changes recommended

Validation bypasses can break generated structure or expose identifiers, and the new snapshot is absent from the released-datasets catalog.

Review effort: Balanced
Findings: 1 · 3

Open (4)

• SSN validation misses labeled unformatted nine-digit values · New
• September dataset snapshot is missing from released_datasets.qmd · New
• Markdown heading validation misses indented and Setext headings · New
• Multiline release titles can inject headings · New

What changed in this PR

Adds an automated, validated release-notes pipeline and public documentation page.

Changes:

• Generates grouped release notes from dated entries during Quarto pre-render.
• Adds collapsible navigation, deep linking, responsive styling, and documentation.
• Adds the September 2026 release entry and generator tests.

File	Description
.github/​pull_request_template.md	Adds release-note checklist guidance.
CONTRIBUTING.md	Documents release-note authoring.
README.md	Describes the generator workflow.
docs/​_quarto.yml	Registers generation and navigation.
docs/​about.qmd	Links the release-notes page.
docs/​assets/​release-notes.js	Implements collapsible sections and deep links.
docs/​release_notes.qmd	Adds generated public output.
docs/​release_notes/​2026-09-10.qmd	Adds the initial release entry.
docs/​release_notes/​README.md	Adds authoring instructions.
docs/​release_notes/​_template.qmd	Provides an entry template.
docs/​released_datasets.qmd	Cross-links release notes.
docs/​styles.css	Styles release-note sections and tables.
scripts/​generate_release_notes.py	Validates and generates release notes.
tests/​test_release_notes.py	Tests generator invariants.

---

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

[Copilot]

Copilot review overview

🔵 Needs a closer look

Validation can be bypassed by mixed code fences and accepts summaries or bodies that break the required heading structure.

Review effort: Balanced
Findings: None

Resolved since last review (4)

• SSN validation misses labeled unformatted nine-digit values
• Multiline release titles can inject headings
• Markdown heading validation misses indented and Setext headings
• September dataset snapshot is missing from released_datasets.qmd

Previously missed (1)

In code that hasn't changed since last review

Match closing fences to the opening delimiter

scripts/​generate_release_notes.py:184

The fence state toggles for any ``` or ~~~ line, even when its delimiter does not match the opening fence. For example, ```\n~~~\n```\n## Escaped validation returns no problems: the ~~~ incorrectly closes the backtick fence, the real closing backticks reopen it, and the page-level heading is treated as code. Track the opening delimiter character and length, and only close on a matching delimiter of at least that length; add this mixed-delimiter case as a regression test.

This issue also appears in the following locations of the same file:

• line 231
• line 264

[Copilot]

Copilot review overview

🟡 Changes recommended

Fence detection can let a release-level heading bypass validation.

Review effort: Balanced
Findings: 1

Open (1)

• Restrict fenced block indentation to three spaces · New

[Copilot]

Copilot review overview

🟡 Changes recommended

Validation gaps can permit malformed entries, duplicate anchors, and formatted or wrapped identifiers to reach the public page.

Review effort: Balanced
Findings: 1

Open (1)

• Detect identifiers across Markdown wrapping and inline formatting · New

Resolved since last review (1)

• Restrict fenced block indentation to three spaces

Previously missed (2)

In code that hasn't changed since last review

Reject entries without level-3 change headings

scripts/​generate_release_notes.py:306

This only rejects an empty body; a nonempty entry with plain prose (or only #### headings) passes even though the generated page requires each change to start at ###. Such an entry produces a release with zero change sections and breaks the documented hierarchy/counting behavior. Track whether an unfenced level-3 heading was seen and reject the entry when none exists.

Check rendered fields for duplicate span IDs

scripts/​generate_release_notes.py:328

The uniqueness pass scans only entry.body, although summary and title are also rendered as Markdown. An explicit span ID such as summary: "[Details]{#release-2026-06-08}" can therefore duplicate a generated release anchor and make deep links resolve unpredictably despite the claimed page-wide guarantee. Include all rendered entry fields in this check.

[Copilot]

Copilot review overview

🟡 Changes recommended

Publication validation permits active Markdown content, and Docker imports create host-unreadable files.

Review effort: Balanced
Findings: 2

Open (2)

• Block unsafe Markdown URLs and HTML attributes · New
• Set imported files to repository-readable permissions · New

Resolved since last review (1)

• Detect identifiers across Markdown wrapping and inline formatting

[Copilot]

🔵 Needs a closer look

The broad release contract and credentialed production deployment path require final human validation despite extensive automated coverage.

0 open findings

2 resolved since last review

• Set imported files to repository-readable permissions
• Block unsafe Markdown URLs and HTML attributes

🧠 Review effort: Balanced