Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .changeset/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
18 changes: 18 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
## What and why

<!-- What does this change, and why? Link the Linear issue (e.g. NNK-123). -->

## Docs impact

<!-- Pick one. User-facing changes need a `docs:` note in their changeset (see AGENTS.md, Releases). -->

- [ ] None
- [ ] Docs page(s) affected: <!-- list the pages on prp-docs.nnkogift.dev -->
- [ ] 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
23 changes: 23 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down
16 changes: 16 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
222 changes: 222 additions & 0 deletions scripts/docs-impact.mjs
Original file line number Diff line number Diff line change
@@ -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 `- <commit>: ` 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 `## <version>`, 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: '<value>'` 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() {

Check warning on line 182 in scripts/docs-impact.mjs

View workflow job for this annotation

GitHub Actions / fallow

High CRAP score (moderate)

Function 'main' has a CRAP score of 42 (threshold: 30). • Severity: moderate • Cyclomatic: 6 • Cognitive: 6 • CRAP: 42 (threshold: 30) • Lines: 34 CRAP combines complexity with coverage: high CRAP means changes here carry high risk. Consider adding tests, simplifying the function, or both.
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()
}
Loading