From 47b1e16ba7ee474e5f34543f0c590006886414c2 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 26 Oct 2026 07:06:37 +0300 Subject: [PATCH] docs: generate the release notes page from the app changelog (NNK-198) Adds scripts/generate-release-notes.mjs (pnpm generate:release-notes), which reads the app's Changesets CHANGELOG.md from GitHub or --from a local path and writes it between the generated markers, and a release-notes workflow that regenerates the page on app-released or manual dispatch and opens a PR. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01LZTKXxVkBdpd1uHuJWerFT --- .github/workflows/release-notes.yml | 57 +++++++ docs/help/release-notes.md | 104 ++++++++++++- package.json | 1 + scripts/generate-release-notes.mjs | 232 ++++++++++++++++++++++++++++ 4 files changed, 389 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/release-notes.yml create mode 100644 scripts/generate-release-notes.mjs diff --git a/.github/workflows/release-notes.yml b/.github/workflows/release-notes.yml new file mode 100644 index 0000000..c5fb2e1 --- /dev/null +++ b/.github/workflows/release-notes.yml @@ -0,0 +1,57 @@ +name: Release notes + +# Regenerates docs/help/release-notes.md from the app's CHANGELOG.md and opens a PR when it changed. +# The app's release job sends `repository_dispatch` with type `app-released`. + +on: + repository_dispatch: + types: [app-released] + workflow_dispatch: + +permissions: + contents: write + pull-requests: write + +concurrency: + group: release-notes + cancel-in-progress: false + +jobs: + regenerate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version-file: .nvmrc + # The script has no dependencies, so no install step is needed. + # The branch comes from the dispatch payload, so check it before it reaches the shell. + - name: Resolve the app branch + id: app-ref + env: + APP_REF: ${{ github.event.client_payload.ref || 'alpha' }} + run: | + ref="${APP_REF#refs/heads/}" + if [[ ! "$ref" =~ ^[A-Za-z0-9][A-Za-z0-9._/-]{0,99}$ ]] || [[ "$ref" == *..* ]]; then + echo "::error::Invalid app branch in client_payload.ref" + exit 1 + fi + echo "ref=$ref" >> "$GITHUB_OUTPUT" + - name: Generate release notes + env: + APP_REF: ${{ steps.app-ref.outputs.ref }} + run: | + node scripts/generate-release-notes.mjs \ + --from "https://raw.githubusercontent.com/nnkogift/program-rules-playground/${APP_REF}/CHANGELOG.md" + - name: Open a pull request + uses: peter-evans/create-pull-request@v7 + with: + branch: chore/release-notes + delete-branch: true + add-paths: docs/help/release-notes.md + commit-message: 'docs: regenerate release notes from the app changelog' + title: 'docs: regenerate release notes from the app changelog' + body: | + Regenerates the Release notes page from the app's `CHANGELOG.md` on the `${{ steps.app-ref.outputs.ref }}` branch. + + Triggered by `${{ github.event_name }}`${{ github.event.client_payload.version && format(' for {0}', github.event.client_payload.version) || '' }}. diff --git a/docs/help/release-notes.md b/docs/help/release-notes.md index e070bce..42dff78 100644 --- a/docs/help/release-notes.md +++ b/docs/help/release-notes.md @@ -1,15 +1,109 @@ --- title: 'Release notes' -description: 'Lists what changed in each release of the app.' +description: 'Lists what changed in each release of Program Rules Playground, newest first.' sidebar_position: 3 --- # Release notes -This page lists what changed in each release of the app. +This page lists what changed in each release of the app, newest first. Program Rules Playground is in its alpha channel: versions end in `-alpha.N`, features and labels can still change between releases, and some notes describe behaviour that a later release changed. Older notes keep the names the app used at the time, for example **Trigger server rules**, which is now **Preview server effects**. The downloads and the full history are on the [GitHub releases page](https://github.com/nnkogift/program-rules-playground/releases). -:::info Draft +To see which version you have, open the program list and select **About** at the bottom of the page. -This page is a stub. The content is coming in a later release of the docs. + -::: + + +## 0.1.0-alpha.11 + +### Fixes and improvements + +- Place event form fields inside their program stage sections by bumping `@nnkogift/dhis2-form-utils-*` to `0.1.0-alpha.13`, and call `useMemo` before the early return in `EventFormFields` + +## 0.1.0-alpha.10 + +### New features and changes + +- Fields made mandatory by a program rule are now marked with an asterisk in their label. +- Select the organisation unit from a modal tree limited to the program's assigned org units (searchable, with unassigned ancestors shown but not selectable). The same selector is used for org unit fields inside forms. Validate form, Verify with server and Save now require an org unit and flag the selector when it is missing. +- Splits the event form submit into **Save** (posts `ACTIVE`) and **Complete** (posts `COMPLETED` with `completedAt`). The registration form keeps a single action, and `status` is never sent as a data value. +- The registration form now opens the server effects summary (with **Verify with server**) before posting, like the event form. The actions are renamed to **Trigger server rules** (registration and event Save) and **Trigger on-complete rules** (event Complete). +- Registration and event forms have a Validate form button that runs form validation and highlights field issues without posting anything. +- Adds **Verify with server** to the save review dialog. It posts the exact event payload with `importMode=VALIDATE&async=false` (nothing is saved), attributes the server's rule errors and warnings to their rules, flags rules only the server fired as "Server only", and lists other import errors separately. + +### Fixes and improvements + +- Updates the `@nnkogift/dhis2-form-utils-*` packages to `0.1.0-alpha.12`. +- Fixes saving events and registrations that could not be submitted: numeric and boolean values are now accepted, and `orgUnit` and the date fields (which the form resolver strips) are restored before validation and kept after the post-save reset. +- Redesigns the footer of the server review dialog. Status, import errors and the dry-run note are one compact block beside the actions, the duplicate Cancel is gone (Close does the same), and a failed verification raises an alert instead of a notice box in the footer. +- The review dialog actions no longer wrap onto two lines, and a failed retry keeps the last good server check on screen instead of clearing it. +- Polishes the server review dialog: verification results are announced to screen readers, a status line says when the server check finished (including a clean run), the button becomes **Verify again**, Cancel moves before Verify, and other import errors show their code as a tag without the importer's backticks. Result messages now say server rules were triggered instead of saved. +- Adds a `typecheck` script and CI job, fixes a strict-mode type error for programs without a `code`, and refreshes the agent guidance (`AGENTS.md` is now the single source, imported by `CLAUDE.md`). +- Validate form now reports invalid results too: a focused alert lists the fields with issues (each links to its field) and a failed validation is shown instead of being swallowed. Shared by the registration and event forms. +- Verify with server now sits beside Validate form instead of in the server summary modal. Rule errors from the dry run appear on the fields they target, and anything else shows in a notice. The summary modal is read-only, and its Trigger server rules button, which posted the payload, is removed. + +## 0.1.0-alpha.9 + +### Fixes and improvements + +- Fixes issues with rule list not showing any rules in scope for event programs +- Refactors the app to follow the team's coding standards: dedupes magic strings into `as const` objects, enables TypeScript strict mode (fixing the nullability gaps and one real bug it surfaced), validates DHIS2 API responses and form payloads with Zod, reorganizes `src` into `modules/program-list`, `modules/program-playground`, and `shared`, and decomposes `EnrollmentRail`/`ProgramPage` into smaller components. No user-facing behavior changes. + +## 0.1.0-alpha.8 + +### Fixes and improvements + +- Adds description to program rule condition in the details modal. Adds links to maintenance apps in the program rules details modal. Improvements on Coordinate and GeoJSON fields + +## 0.1.0-alpha.7 + +### Fixes and improvements + +- Move rule feedback and indicators into a persistent sidebar with separate Feedback/Indicators cards, replacing the inline tinted banner + +## 0.1.0-alpha.6 + +### Fixes and improvements + +- Fixes and improvements on the rules list filtering and performance improvements + +## 0.1.0-alpha.5 + +### Fixes and improvements + +- Code-split routes and program forms with React.lazy + +## 0.1.0-alpha.4 + +### Fixes and improvements + +- The rules are now sorted to allow those firing to move on top + +## 0.1.0-alpha.3 + +### Fixes and improvements + +- Fix issues with multi value texts throwing errors +- Updates on devtools panel + +## 0.1.0-alpha.2 + +### Fixes and improvements + +- Performance fixes +- Move the add-event button inline next to repeatable stage labels + +## 0.1.0-alpha.1 + +### Fixes and improvements + +- Fixes issues with missing renderType causing whole form to crash +- Fixes issues with event form displays fields outside of sections + +## 0.1.0-alpha.0 + +### New features and changes + +- Initial release + + diff --git a/package.json b/package.json index 030016e..37be7ad 100644 --- a/package.json +++ b/package.json @@ -13,6 +13,7 @@ "typecheck": "tsc --noEmit && tsc --noEmit -p scripts", "format": "prettier --write .", "generate:reference": "node --experimental-strip-types scripts/generate-reference.mts", + "generate:release-notes": "node scripts/generate-release-notes.mjs", "lint": "prettier --check . && pnpm typecheck && markdownlint-cli2", "prepare": "husky", "screenshots": "node --env-file-if-exists=.env scripts/screenshots/run.mts", diff --git a/scripts/generate-release-notes.mjs b/scripts/generate-release-notes.mjs new file mode 100644 index 0000000..58d750f --- /dev/null +++ b/scripts/generate-release-notes.mjs @@ -0,0 +1,232 @@ +#!/usr/bin/env node +// Generates docs/help/release-notes.md from the app's Changesets CHANGELOG.md. +// +// Usage: +// node scripts/generate-release-notes.mjs # fetch from GitHub (alpha branch) +// node scripts/generate-release-notes.mjs --from # read a local CHANGELOG.md +// node scripts/generate-release-notes.mjs --from # fetch another raw URL +// node scripts/generate-release-notes.mjs --out # write another page +// +// Only the text between the generated markers in the page is replaced. + +import { readFile, writeFile } from 'node:fs/promises'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const DEFAULT_SOURCE = + 'https://raw.githubusercontent.com/nnkogift/program-rules-playground/alpha/CHANGELOG.md'; +const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); +const DEFAULT_OUT = path.join(REPO_ROOT, 'docs/help/release-notes.md'); +const START_MARKER = ''; +const END_MARKER = ''; + +// Changesets section headings, mapped to user-facing headings. +const SECTION_TITLES = { + 'major changes': 'Breaking changes', + 'minor changes': 'New features and changes', + 'patch changes': 'Fixes and improvements', +}; + +// Notes with these conventional-commit prefixes are for maintainers, not users. +const INTERNAL_PREFIXES = ['docs', 'chore', 'ci', 'test', 'build']; + +function parseArgs(argv) { + const args = { from: DEFAULT_SOURCE, out: DEFAULT_OUT }; + for (let i = 0; i < argv.length; i += 1) { + const arg = argv[i]; + if (arg === '--from' || arg === '--out') { + const value = argv[i + 1]; + if (!value) throw new Error(`${arg} needs a value`); + args[arg.slice(2)] = value; + i += 1; + } else if (arg === '--help' || arg === '-h') { + console.log('Usage: generate-release-notes.mjs [--from ] [--out ]'); + process.exit(0); + } else { + throw new Error(`Unknown argument: ${arg}`); + } + } + return args; +} + +async function readSource(source) { + if (/^https?:\/\//.test(source)) { + const response = await fetch(source); + if (!response.ok) { + throw new Error(`Could not fetch ${source}: HTTP ${response.status}`); + } + return response.text(); + } + return readFile(source, 'utf8'); +} + +// Splits "## " blocks into { version, sections: [{ title, entries }] }. +function parseChangelog(text) { + const releases = []; + let release = null; + let section = null; + let entry = null; + + const pushEntry = () => { + if (entry && section) section.entries.push(entry); + entry = null; + }; + + for (const rawLine of text.split(/\r?\n/)) { + const line = rawLine.replace(/\s+$/, ''); + const versionMatch = /^## (.+)$/.exec(line); + const sectionMatch = /^### (.+)$/.exec(line); + const entryMatch = /^- (.*)$/.exec(line); + + if (versionMatch) { + pushEntry(); + release = { version: versionMatch[1].trim(), sections: [] }; + section = null; + releases.push(release); + } else if (sectionMatch && release) { + pushEntry(); + section = { title: sectionMatch[1].trim(), entries: [] }; + release.sections.push(section); + } else if (entryMatch && section) { + pushEntry(); + entry = [entryMatch[1]]; + } else if (entry && line.trim() !== '') { + entry.push(line); + } else if (line.trim() === '') { + pushEntry(); + } + } + pushEntry(); + return releases; +} + +// Removes the commit hash Changesets puts in front of each note, in plain +// ("abc1234: ") or linked ("[`abc1234`](url) ") form, plus PR links and thanks. +function stripHash(text) { + return text + .replace(/^\[#\d+\]\([^)]*\)\s*/, '') + .replace(/^\[`?[0-9a-f]{7,40}`?\]\([^)]*\)\s*/, '') + .replace(/^`?[0-9a-f]{7,40}`?:\s*/, '') + .replace(/^Thanks \[@[^\]]+\]\([^)]*\)!\s*-\s*/, ''); +} + +// A note can be a single line, a paragraph over several lines, or a nested +// list ("- abc1234: - fix: one\n - fix: two"). Returns flat note strings. +function splitNotes(lines) { + const [first, ...rest] = lines; + const head = stripHash(first.trim()); + const nested = []; + if (head.startsWith('- ')) nested.push([head.slice(2)]); + else nested.push([head]); + + for (const line of rest) { + const item = /^\s+- (.*)$/.exec(line); + if (item) nested.push([item[1]]); + else nested[nested.length - 1].push(line.trim()); + } + return nested.map((parts) => parts.join(' ').replace(/\s+/g, ' ').trim()).filter(Boolean); +} + +function isInternal(note) { + const match = /^([a-z]+)(\([^)]*\))?!?:/i.exec(note); + return Boolean(match && INTERNAL_PREFIXES.includes(match[1].toLowerCase())); +} + +// "fix: something" -> "Something". Keeps the note otherwise unchanged. +function tidy(note) { + const withoutPrefix = note.replace( + /^(feat|fix|perf|refactor|style|revert)(\([^)]*\))?!?:\s*/i, + '' + ); + return withoutPrefix.charAt(0).toUpperCase() + withoutPrefix.slice(1); +} + +// Docs pages are MDX: escape characters MDX would parse, outside code spans. +function escapeMdx(text) { + return text + .split(/(`[^`]*`)/) + .map((part, index) => + index % 2 === 1 ? part : part.replace(/[{}]/g, '\\$&').replace(/ compareVersionsDesc(a.version, b.version)); + const out = []; + for (const release of sorted) { + out.push(`## ${release.version}`, ''); + let wroteSection = false; + for (const section of release.sections) { + const notes = section.entries + .flatMap(splitNotes) + .filter((note) => !isInternal(note)) + .map((note) => escapeMdx(tidy(note))); + if (!notes.length) continue; + const title = SECTION_TITLES[section.title.toLowerCase()] ?? section.title; + out.push(`### ${title}`, '', ...notes.map((note) => `- ${note}`), ''); + wroteSection = true; + } + if (!wroteSection) out.push('No user-facing changes in this release.', ''); + } + return out.join('\n').trimEnd(); +} + +async function main() { + const args = parseArgs(process.argv.slice(2)); + const changelog = await readSource(args.from); + const releases = parseChangelog(changelog); + if (!releases.length) throw new Error(`No releases found in ${args.from}`); + + const page = await readFile(args.out, 'utf8'); + const start = page.indexOf(START_MARKER); + const end = page.indexOf(END_MARKER); + if (start === -1 || end === -1 || end < start) { + throw new Error(`${args.out} needs ${START_MARKER} and ${END_MARKER} markers`); + } + + const next = `${page.slice(0, start + START_MARKER.length)}\n\n${render(releases)}\n\n${page.slice(end)}`; + if (next === page) { + console.log(`${path.relative(REPO_ROOT, args.out)} is up to date`); + return; + } + await writeFile(args.out, next); + console.log(`Wrote ${releases.length} releases to ${path.relative(REPO_ROOT, args.out)}`); +} + +main().catch((error) => { + console.error(error.message); + process.exit(1); +});