From e51a664f53f816cd827722d1e4a54b618638ef02 Mon Sep 17 00:00:00 2001 From: Ziyu Zhu Date: Thu, 6 Aug 2026 21:13:06 -0500 Subject: [PATCH] docs: make release notes user-facing --- .../labkit-documentation-maintainer/SKILL.md | 12 ++++ .github/RELEASE_NOTES_TEMPLATE.md | 19 ++++++ .github/workflows/release.yml | 4 +- AGENTS.md | 6 ++ .../maintain-and-release/release.md | 22 ++++++- ...LK-20260806-reader-facing-release-notes.md | 60 +++++++++++++++++++ .../specs/tests/labkittest/TestCatalogSpec.m | 8 +++ 7 files changed, 126 insertions(+), 5 deletions(-) create mode 100644 .github/RELEASE_NOTES_TEMPLATE.md create mode 100644 docs/history/records/2026/08/LK-20260806-reader-facing-release-notes.md diff --git a/.agents/skills/labkit-documentation-maintainer/SKILL.md b/.agents/skills/labkit-documentation-maintainer/SKILL.md index 78372937..fce15b04 100644 --- a/.agents/skills/labkit-documentation-maintainer/SKILL.md +++ b/.agents/skills/labkit-documentation-maintainer/SKILL.md @@ -70,6 +70,18 @@ scope, behavior, documentation/boundary decisions, delivery state, and data hygiene. Never place sensitive lab data or local absolute paths in an Issue or PR. +## Release notes + +Treat a GitHub Release as a user interface for deciding whether and how to +upgrade. Preserve historical facts, breaking changes, safety warnings, and +required migration actions, but express them through user-visible workflows +and supported contracts. Do not turn the note into a delivery log: omit commit +and run identifiers, shell commands, test inventories, CI routing, internal +package moves, hashes, byte counts, and asset-verification procedure. Summarize +validation only at the level useful to a user, such as supported MATLAB and OS +coverage or completed interactive checks. Keep exact evidence in the PR, +workflow record, structured component history, and release verification. + ## Workflow 1. Change authored sources or renderer code. After moving or retiring diff --git a/.github/RELEASE_NOTES_TEMPLATE.md b/.github/RELEASE_NOTES_TEMPLATE.md new file mode 100644 index 00000000..e50ca1ba --- /dev/null +++ b/.github/RELEASE_NOTES_TEMPLATE.md @@ -0,0 +1,19 @@ + + + + +## Highlights + + + +## Fixes + + + +## Upgrade Note + + + +## Validation + + diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 14bdca8b..272c262c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -120,7 +120,7 @@ jobs: --repo "$GITHUB_REPOSITORY" \ --verify-tag \ --title "V${RELEASE_TAG#v}" \ - --generate-notes \ + --notes-file .github/RELEASE_NOTES_TEMPLATE.md \ --draft local_digest="sha256:$(cut -d' ' -f1 \ "artifacts/release/${RELEASE_TAG}/asset.sha256")" @@ -141,5 +141,5 @@ jobs: echo "::error::Remote launcher byte count does not match the tag blob." exit 1 fi - echo "Review and complete the release notes, asset, and validation evidence before publishing the draft." \ + echo "Rewrite the release notes for users, then review the asset and validation evidence before publishing the draft." \ >> "$GITHUB_STEP_SUMMARY" diff --git a/AGENTS.md b/AGENTS.md index a217a01e..330f6a4d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -314,6 +314,12 @@ explicit compliant squash subject; do not rely on GitHub defaults. - New release tags are `vX.Y.Z`; do not rename published legacy tags. Release titles contain only `VX.Y.Z` with an uppercase `V` and relevant `Highlights`, `Fixes`, `Upgrade Note`, and `Validation` sections. +- Treat release notes as a user-facing product summary, not a release audit. + Describe observable behavior, affected workflows, compatibility, and actions + a user may need to take. Do not publish commit or run identifiers, commands, + test inventories, CI architecture, internal package movement, hashes, byte + counts, or maintainer-only evidence; keep those in the PR, workflow record, + structured history, or release asset verification. - Start the manual `Release` workflow only after developer-led interactive App validation, successful required PR validation, and a successful lightweight `Continuous Integration` main-push run for the exact squash commit. It then diff --git a/docs/development/maintain-and-release/release.md b/docs/development/maintain-and-release/release.md index 2157eb37..a4add2d7 100644 --- a/docs/development/maintain-and-release/release.md +++ b/docs/development/maintain-and-release/release.md @@ -105,7 +105,23 @@ Use this note structure: ``` Omit an empty section when it does not apply. Keep validation factual: name the -commands or CI workflow that passed and the commit used for the release. +supported MATLAB and operating-system coverage, relevant interactive checks, +or other assurance a user can interpret. + +Release notes are a user-facing product summary, not a release audit or a +shortened PR description. Each statement should help a reader understand what +changed in a supported workflow, whether an issue they experienced was fixed, +whether existing work remains compatible, or what action an upgrade requires. +Use App and workflow names that users recognize. Preserve safety warnings and +breaking-change guidance even when they affect only custom App authors. + +Do not publish commit or workflow-run identifiers, pull-request links, shell +commands, test inventories, CI routing, internal package movement, file hashes, +byte counts, or asset-verification procedure in release notes. Those details +remain available in the PR review record, structured component history, +workflow record, and release asset checks. The +`.github/RELEASE_NOTES_TEMPLATE.md` draft prompts the required reader-facing +sections and must be rewritten for the actual release before publication. After it verifies the required CI run, the workflow exports `labkit_launcher.m` from the annotated tag blob, verifies its SHA-256 against @@ -116,8 +132,8 @@ by that Base MATLAB CI run; a later advance of `main` does not move it. Automation deliberately stops at a draft. Before publishing, rewrite or complete the generated notes with the required sections above, confirm the version and tag target, inspect the launcher asset, and record the final manual -and CI evidence. Publishing the draft is a developer release decision, not a -side effect of ordinary CI. +and CI evidence outside the public note. Publishing the draft is a developer +release decision, not a side effect of ordinary CI. Attach `labkit_launcher.m` to each GitHub release. The root README download link points at the latest release asset so browsers download the launcher diff --git a/docs/history/records/2026/08/LK-20260806-reader-facing-release-notes.md b/docs/history/records/2026/08/LK-20260806-reader-facing-release-notes.md new file mode 100644 index 00000000..dd07e935 --- /dev/null +++ b/docs/history/records/2026/08/LK-20260806-reader-facing-release-notes.md @@ -0,0 +1,60 @@ +# Release notes describe the product for users + +```labkit-change +id: LK-20260806-reader-facing-release-notes +date: 2026-08-06 +sequence: 177 +type: docs +compatibility: compatible +scope: Release communication +scope: GitHub Release history +``` + +## Context + +Release notes had gradually accumulated delivery evidence and implementation +detail that belonged in pull requests, workflow records, and asset checks. That +made it harder for readers to understand what a release changed for them. + +## Decision and rationale + +Treat every GitHub Release as a user-facing product summary. Notes describe +recognizable workflows, corrected behavior, compatibility, safety warnings, +and required upgrade actions. Maintainer evidence remains available at its +own source instead of competing with the release summary. + +## Changes + +- Historical Release notes were rewritten around user-visible outcomes. +- The release manual and agent guidance now exclude delivery logs and internal + implementation evidence from public notes. +- New draft Releases start from a reader-facing section template instead of an + automatically generated commit list. + +## User and data impact + +Users can compare releases without interpreting repository or CI details. No +App behavior, scientific data, projects, results, or public API changed. + +## Compatibility and migration + +Published tags, release titles, dates, assets, and version identities remain +unchanged. Existing downloads require no action. + +## Validation + +All published Release bodies were reviewed for the required reader-facing +structure and scanned for maintainer-only delivery evidence. Repository tests +cover the draft template and release workflow contract. + +## Evidence + +- Every published Release retains its original tag and title. +- The online notes contain no commit hashes, workflow-run links, commands, or + asset digests. +- Focused release and documentation checks are required before integration. + +## Known limitations and follow-up + +Historical notes remain summaries of their original releases; they do not +retroactively add behavior that was not delivered at the time. diff --git a/tests/specs/tests/labkittest/TestCatalogSpec.m b/tests/specs/tests/labkittest/TestCatalogSpec.m index 618c419e..a98485a9 100644 --- a/tests/specs/tests/labkittest/TestCatalogSpec.m +++ b/tests/specs/tests/labkittest/TestCatalogSpec.m @@ -587,6 +587,8 @@ function releaseAssetIntegrityUsesDigestAndByteCount(testCase) root = labkittest.setup(); workflow = string(fileread(fullfile( ... root, ".github", "workflows", "release.yml"))); + notes = string(fileread(fullfile( ... + root, ".github", "RELEASE_NOTES_TEMPLATE.md"))); testCase.verifySubstring(workflow, ... "Remote launcher digest does not match the tag blob."); @@ -600,8 +602,14 @@ function releaseAssetIntegrityUsesDigestAndByteCount(testCase) "gh release verify-asset")); testCase.verifySubstring(workflow, ... '--title "V${RELEASE_TAG#v}"'); + testCase.verifySubstring(workflow, ... + "--notes-file .github/RELEASE_NOTES_TEMPLATE.md"); + testCase.verifyFalse(contains(workflow, "--generate-notes")); testCase.verifyFalse(contains(workflow, ... '--title "LabKit MATLAB Workbench')); + testCase.verifySubstring(notes, "## Highlights"); + testCase.verifySubstring(notes, "## Upgrade Note"); + testCase.verifySubstring(notes, "## Validation"); end function explainChangedReportsClassificationAndExactEvidence(testCase)