diff --git a/.changeset/README.md b/.changeset/README.md index 654c6d4..88d5b40 100644 --- a/.changeset/README.md +++ b/.changeset/README.md @@ -6,3 +6,19 @@ find the full documentation for it [in our repository](https://github.com/change We have a quick list of common questions to get you started engaging with this project in [our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md). + +## Docs notes + +If your change affects what users see, add a line starting with `docs:` after the summary, in its own paragraph, describing what the docs must change. For example: + +```md +--- +'program-rules-playground': patch +--- + +Shows the rule name in the Verify with server notice. + +docs: Update the notice screenshot in "Check rules against the server". +``` + +The release workflow collects these lines from `CHANGELOG.md` and opens a docs issue in `nnkogift/program-rules-playground-docs`. Don't start the summary itself with `docs:`; only lines after it are collected. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..3b1a57c --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,18 @@ +## What and why + + + +## Docs impact + + + +- [ ] None +- [ ] Docs page(s) affected: +- [ ] Screenshots change + +If this changes `minDHIS2Version` or `maxDHIS2Version` in `d2.config.js`, say so here and update `SUPPORTED_DHIS2_RANGE` in `src/shared/constants/links.ts` to match. The release workflow flags the change for the DHIS2 version compatibility page. + +## Checks + +- [ ] `pnpm lint`, `pnpm typecheck` and `pnpm test` pass +- [ ] Changeset added (`pnpm changeset`) if users will notice the change diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b7336e6..2fc21dd 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -50,6 +50,29 @@ jobs: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: gh release upload "v${{ steps.version.outputs.version }}" build/bundle/*.zip --clobber + # Tells the docs repo about the release: opens a "Docs impact" issue with + # the changesets' `docs:` notes and any DHIS2 version range change, and + # triggers its screenshot pipeline. A separate job so a docs-side failure + # never blocks the deploy. Skips with a warning without DOCS_REPO_TOKEN. + docs-impact: + needs: release + if: needs.release.outputs.published == 'true' + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@v4 + with: + # Tags and history, to diff d2.config.js against the previous release. + fetch-depth: 0 + - uses: actions/setup-node@v4 + with: + node-version: 24 + - name: Open docs issue and trigger screenshots + env: + DOCS_REPO_TOKEN: ${{ secrets.DOCS_REPO_TOKEN }} + run: node scripts/docs-impact.mjs + deploy: needs: release if: needs.release.outputs.published == 'true' diff --git a/AGENTS.md b/AGENTS.md index 27d6fc5..5ee32f7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -105,3 +105,19 @@ Jest + Testing Library; tests sit next to the code as `*.test.ts(x)`. `usehooks- ### Releases Changesets with conventional commits (`changeset-conventional-commits`); keep the `@nnkogift/dhis2-form-utils-*` versions in `package.json` aligned with each other. `pnpm-workspace.yaml` exempts those packages from pnpm's minimum release age so fresh alphas can be installed. + +Releases run from `.github/workflows/release.yml` on pushes to `alpha`: `changesets/action` opens the version PR, and once it is merged `scripts/release.mjs` builds the bundle and tags the release. + +**Docs impact.** When a changeset changes something users see, add a line starting with `docs:` after the summary, in its own paragraph, saying what the docs must change: + +```md +--- +'program-rules-playground': minor +--- + +Renames the Show hidden fields toggle to Show placeholders. + +docs: Rename the toggle in "Read field badges and hidden-field placeholders" and retake its screenshot. +``` + +After a release, the `docs-impact` job runs `scripts/docs-impact.mjs`. It reads the `docs:` lines from the new version's `CHANGELOG.md` section (the changelog generator copies changeset bodies there), compares `minDHIS2Version`/`maxDHIS2Version` in `d2.config.js` with the previous tag, and, in [`nnkogift/program-rules-playground-docs`](https://github.com/nnkogift/program-rules-playground-docs), opens a `Docs impact: program-rules-playground vX` issue when either found something and sends the `app-released` (always) and `app-compat-changed` (range changed) repository dispatches. It needs the `DOCS_REPO_TOKEN` secret and skips with a warning without it. Run `node scripts/docs-impact.mjs --dry-run` to see what it would do. The PR template (`.github/pull_request_template.md`) asks for the docs impact of every PR. diff --git a/scripts/docs-impact.mjs b/scripts/docs-impact.mjs new file mode 100644 index 0000000..cbc9ba0 --- /dev/null +++ b/scripts/docs-impact.mjs @@ -0,0 +1,222 @@ +import { execFileSync } from 'node:child_process' +import { readFileSync } from 'node:fs' +import { pathToFileURL } from 'node:url' + +// Run by the `docs-impact` job in release.yml after a release is published. +// It tells the docs repo what changed: +// +// 1. Collects the `docs:` notes of the changesets in this release. In pre +// mode Changesets keeps the changeset files, outside it deletes them, so +// neither is reliable. The changelog generator (`@changesets/cli/changelog`) +// copies every changeset body into CHANGELOG.md, indenting the lines after +// the summary under the bullet, so we read them from this version's +// CHANGELOG section instead: any line whose trimmed text starts with +// `docs:`. The summary line itself is prefixed with `- : ` and +// never matches. +// 2. Compares minDHIS2Version/maxDHIS2Version in d2.config.js with the +// previous release tag, for the compatibility page. +// 3. Opens a "Docs impact" issue in the docs repo when either found +// something (once per version), and fires `app-released` (always) and +// `app-compat-changed` (when the range changed) repository dispatches so +// the docs screenshot pipeline can run. +// +// Needs DOCS_REPO_TOKEN (fine-grained PAT, issues:write and contents:read on +// the docs repo). Without it the script warns and exits 0, so a missing +// secret never fails a release. Pass --dry-run to print instead of calling gh. + +const APP_REPO = 'nnkogift/program-rules-playground' +const DOCS_REPO = 'nnkogift/program-rules-playground-docs' +const DOCS_NOTE = /^docs:\s*(.+)$/i +const VERSION_HEADING = /^## / + +/** The lines of CHANGELOG.md under `## `, up to the next version. */ +export function changelogSection(changelog, version) { + const lines = changelog.split('\n') + const start = lines.findIndex((line) => line.trim() === `## ${version}`) + if (start === -1) { + return [] + } + const rest = lines.slice(start + 1) + const end = rest.findIndex((line) => VERSION_HEADING.test(line)) + return end === -1 ? rest : rest.slice(0, end) +} + +/** The `docs:` notes in a changelog section, without the prefix. */ +export function collectDocsNotes(sectionLines) { + return sectionLines + .map((line) => DOCS_NOTE.exec(line.trim())?.[1]?.trim()) + .filter(Boolean) +} + +/** Reads a `key: ''` string from d2.config.js source. */ +export function readConfigValue(source, key) { + const match = new RegExp(`${key}\\s*:\\s*['"]([^'"]+)['"]`).exec(source) + return match?.[1] +} + +export function readVersionRange(source) { + return { + min: readConfigValue(source, 'minDHIS2Version'), + max: readConfigValue(source, 'maxDHIS2Version'), + } +} + +export function buildIssueBody({ version, notes, compat }) { + const releaseUrl = `https://github.com/${APP_REPO}/releases/tag/v${version}` + const parts = [ + `[program-rules-playground v${version}](${releaseUrl}) was released. Update the docs for the changes below.`, + ] + if (notes.length > 0) { + parts.push( + '## Docs notes from the changesets', + notes.map((note) => `- [ ] ${note}`).join('\n') + ) + } + if (compat) { + parts.push( + '## DHIS2 version range changed', + `- [ ] Update the DHIS2 version compatibility page: ${compat.before.min} to ${compat.before.max} is now ${compat.after.min} to ${compat.after.max}.` + ) + } + parts.push( + '_Opened by the release workflow of the app repo. The screenshot pipeline was triggered with `app-released`._' + ) + return parts.join('\n\n') +} + +function git(...args) { + return execFileSync('git', args, { encoding: 'utf8' }).trim() +} + +function previousTag(tag) { + try { + return git( + 'describe', + '--tags', + '--abbrev=0', + '--match', + 'v*', + `${tag}^` + ) + } catch { + return undefined + } +} + +function compatChange(tag) { + const before = previousTag(tag) + if (!before) { + return undefined + } + const range = { + before: readVersionRange(git('show', `${before}:d2.config.js`)), + after: readVersionRange(readFileSync('./d2.config.js', 'utf8')), + } + const changed = + range.before.min !== range.after.min || + range.before.max !== range.after.max + return changed ? range : undefined +} + +function createGh({ token, dryRun }) { + return (...args) => { + if (dryRun) { + console.log(`[dry run] gh ${args.join(' ')}`) + return '[]' + } + return execFileSync('gh', args, { + encoding: 'utf8', + env: { ...process.env, GH_TOKEN: token }, + }).trim() + } +} + +function dispatch(gh, eventType, payload) { + const fields = Object.entries(payload).flatMap(([key, value]) => [ + '-f', + `client_payload[${key}]=${value}`, + ]) + gh( + 'api', + `repos/${DOCS_REPO}/dispatches`, + '-f', + `event_type=${eventType}`, + ...fields + ) + console.log(`Sent ${eventType} to ${DOCS_REPO}.`) +} + +function openIssue(gh, { version, notes, compat }) { + const title = `Docs impact: program-rules-playground v${version}` + const existing = JSON.parse( + gh( + 'issue', + 'list', + '--repo', + DOCS_REPO, + '--state', + 'all', + '--search', + `"${title}" in:title`, + '--json', + 'number' + ) || '[]' + ) + if (existing.length > 0) { + console.log(`${title} already exists (#${existing[0].number}).`) + return + } + gh( + 'issue', + 'create', + '--repo', + DOCS_REPO, + '--title', + title, + '--body', + buildIssueBody({ version, notes, compat }) + ) + console.log(`Opened "${title}" in ${DOCS_REPO}.`) +} + +function main() { + const dryRun = process.argv.includes('--dry-run') + const token = process.env.DOCS_REPO_TOKEN + if (!token && !dryRun) { + console.log( + '::warning title=Docs impact skipped::DOCS_REPO_TOKEN is not set, so no docs issue was opened and the screenshot pipeline was not triggered.' + ) + return + } + + const { version } = JSON.parse(readFileSync('./package.json', 'utf8')) + const notes = collectDocsNotes( + changelogSection(readFileSync('./CHANGELOG.md', 'utf8'), version) + ) + const compat = compatChange(`v${version}`) + const gh = createGh({ token, dryRun }) + + console.log(`v${version}: ${notes.length} docs note(s).`) + dispatch(gh, 'app-released', { version }) + if (compat) { + dispatch(gh, 'app-compat-changed', { + version, + minDHIS2Version: compat.after.min, + maxDHIS2Version: compat.after.max, + }) + } + if (notes.length > 0 || compat) { + openIssue(gh, { version, notes, compat }) + } else { + console.log( + 'No docs notes and no version range change, no issue opened.' + ) + } +} + +if ( + process.argv[1] && + import.meta.url === pathToFileURL(process.argv[1]).href +) { + main() +}