From 162766b14e53bbf76113b51df1cdaecd30e66b80 Mon Sep 17 00:00:00 2001 From: Benjamin Canac Date: Wed, 18 Nov 2026 12:40:54 +0100 Subject: [PATCH 1/5] feat(pr): allow customising changelog section headings --- README.md | 1 + pr/action.yml | 5 ++++ scripts/update-changelog.ts | 46 +++++++++++++++++++++++++++++- test/update-changelog-main.test.ts | 21 ++++++++++++++ test/update-changelog.test.ts | 34 +++++++++++++++++++++- 5 files changed, 105 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7fb1b66..74bb81f 100644 --- a/README.md +++ b/README.md @@ -179,6 +179,7 @@ All subactions take a `node-version` input (default `24`; uppt needs `--experime | `allow-forks` | `false` | By default the action skips on forks so they don't open release PRs of their own. | | `prerelease` | _(unset)_ | One-shot prerelease identifier (`beta`, `rc`, or a bare number). See [Prereleases](#prereleases). | | `title` | `v{version}` | Template for the release PR title and commit message, e.g. `chore(release): v{version}`. In [independent mode](#independent-versioning-experimental) the placeholders are `{count}` and `{packages}` (`package` or `packages`), and the default is `chore: release {count} {packages}`. | +| `sections` | _(unset)_ | Changelog section headings to override, one per line as `: `, e.g. `feat: 🚀 Features`. Types left out keep their default heading (`🚀 Enhancements`, `🩹 Fixes`, `🔥 Performance`, ...). | | `pr-notes` | _(unset)_ | Markdown to show in the release PR body below the timetable, such as links to preview builds. `{base}` is replaced with the base branch and, outside [independent mode](#independent-versioning-experimental), `{version}` with the next version (e.g. `1.3.0`). See below. | uppt keeps `pr-notes` in a marked block of the release PR body, refreshes it on every run, and leaves it out of the GitHub release notes. For example, if [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new) runs on pushes to your base branches, you can point at the latest build of the base branch: diff --git a/pr/action.yml b/pr/action.yml index 965656b..2c5d99d 100644 --- a/pr/action.yml +++ b/pr/action.yml @@ -39,6 +39,10 @@ inputs: description: 'Template for the release PR title and the release branch''s commit message. Lockstep mode provides `{version}` (default `v{version}`); independent mode provides `{count}` and `{packages}`, which is `package` or `packages` to match the count (default `chore: release {count} {packages}`).' required: false default: '' + sections: + description: 'Optional changelog section headings, one per line as `<type>: <title>` (e.g. `feat: 🚀 Features`). Types left out keep their default heading.' + required: false + default: '' prerelease: description: 'One-shot prerelease identifier (e.g. `beta`, `rc`, or a bare number like `0`). When set, this run cuts or continues a prerelease: from a stable version the normal bump is applied and the identifier attached at counter 0 (`4.5.2` → `5.0.0-beta.0`); from a prerelease with the same identifier the counter increments (`5.0.0-beta.0` → `5.0.0-beta.1`). Omit for normal releases; a prerelease version with this unset graduates to its stable version. `uppt/publish` stages prereleases under a matching dist-tag (`beta`, `rc`, `next` for a bare number) so `latest` is never moved to them.' required: false @@ -111,5 +115,6 @@ runs: MODE: ${{ inputs.mode }} SCOPES: ${{ inputs.scopes }} TITLE: ${{ inputs.title }} + SECTIONS: ${{ inputs.sections }} PR_NOTES: ${{ inputs.pr-notes }} run: node --experimental-strip-types ${{ github.action_path }}/../scripts/update-changelog.ts diff --git a/scripts/update-changelog.ts b/scripts/update-changelog.ts index f3740a6..05d97c0 100644 --- a/scripts/update-changelog.ts +++ b/scripts/update-changelog.ts @@ -28,6 +28,8 @@ // TITLE release PR title and commit message template, with // `{version}` in lockstep mode and `{count}` / // `{packages}` in independent mode +// SECTIONS newline-separated "<type>: <title>" overrides for +// the changelog section headings // PR_NOTES Markdown kept in a marked block of the release PR // preamble and refreshed on every run, with `{base}` // and, in lockstep mode, `{version}` @@ -81,6 +83,41 @@ const TYPE_TITLES: Record<string, string> = { const KNOWN_TYPES = new Set(Object.keys(TYPE_TITLES)) +/** + * Parse a newline-separated `sections:` input into the changelog section + * headings, starting from the defaults. Each non-blank line takes the + * shape `<type>: <title>`, split on the first colon so the title can hold + * colons of its own (`feat: :rocket: Features`). Lines starting with `#` + * are comments. + */ +export function parseSectionsInput (raw: string): Record<string, string> { + const titles = { ...TYPE_TITLES } + const seen = new Set<string>() + const lines = raw.split(/\r?\n/) + for (let i = 0; i < lines.length; i++) { + const line = lines[i]!.trim() + if (!line || line.startsWith('#')) continue + const colon = line.indexOf(':') + if (colon === -1) { + throw new Error(`\`sections\` entry on line ${i + 1} is missing a colon. Expected "<type>: <title>", got "${line}".`) + } + const type = line.slice(0, colon).trim() + const title = line.slice(colon + 1).trim() + if (!KNOWN_TYPES.has(type)) { + throw new Error(`\`sections\` entry on line ${i + 1} names an unknown type \`${type}\`. Expected one of ${[...KNOWN_TYPES].map(t => `\`${t}\``).join(', ')}.`) + } + if (!title) { + throw new Error(`\`sections\` entry for \`${type}\` has an empty title.`) + } + if (seen.has(type)) { + throw new Error(`\`sections\` entry for \`${type}\` appears more than once.`) + } + seen.add(type) + titles[type] = title + } + return titles +} + const isReleaseWorthy = (c: Commit) => KNOWN_TYPES.has(c.type) && !(c.type === 'chore' && c.scope === 'deps') @@ -508,6 +545,8 @@ export function formatChangelog ( * rendered line: the section heading already names the package. */ packageScopes?: string[] + /** Section headings by commit type, from `parseSectionsInput`. */ + titles?: Record<string, string> }, ): string { const grouped = new Map<string, Commit[]>() @@ -530,7 +569,7 @@ export function formatChangelog ( for (const type of Object.keys(TYPE_TITLES)) { const items = grouped.get(type) if (!items?.length) continue - lines.push(`### ${TYPE_TITLES[type]}`, '') + lines.push(`### ${(opts.titles ?? TYPE_TITLES)[type]}`, '') for (const c of items) { const ownScopes = c.scope.split(',').map(s => s.trim()).filter(Boolean) const redundant = ownScopes.length === 1 && Boolean(opts.packageScopes?.includes(ownScopes[0]!)) @@ -1209,6 +1248,7 @@ export function buildIndependentBody ( repo: string preamble: string contributors?: Contributor[] + titles?: Record<string, string> }, ): string { const releasedNames = new Set(plan.releases.map(r => r.name)) @@ -1223,6 +1263,7 @@ export function buildIndependentBody ( fromRef: release.fromTag, toRef: `${release.name}@${release.newVersion}`, packageScopes: release.scopes, + titles: opts.titles, }), '') } else { const causes = propagationCauses(release, releasedNames) @@ -1359,6 +1400,7 @@ export async function main () { repo: repo.repo, fromRef: latestTag, toRef: `v${newVersion}`, + titles: parseSectionsInput(process.env.SECTIONS ?? ''), }) console.log(`Current: ${currentVersion} -> ${newVersion} (${bump}${pinned ? `, pinned on #${pinned.pr.number}` : ''})`) @@ -1457,6 +1499,7 @@ export async function main () { async function runIndependent (packagesInput: string): Promise<void> { const workspaces = resolveWorkspaces(process.cwd(), packagesInput) const scopeOverrides = parseScopesInput(process.env.SCOPES ?? '') + const titles = parseSectionsInput(process.env.SECTIONS ?? '') const tags = getAllTags() const lockstepTag = latestLockstepTag(tags) @@ -1570,6 +1613,7 @@ async function runIndependent (packagesInput: string): Promise<void> { repo: repo.repo, preamble, contributors, + titles, }) if (dryRun) { diff --git a/test/update-changelog-main.test.ts b/test/update-changelog-main.test.ts index 148cb17..5bd4dcc 100644 --- a/test/update-changelog-main.test.ts +++ b/test/update-changelog-main.test.ts @@ -20,6 +20,7 @@ const ENV_KEYS = [ 'MODE', 'SCOPES', 'TITLE', + 'SECTIONS', 'PR_NOTES', ] as const @@ -286,6 +287,19 @@ describe('lockstep main', () => { expect(prBody()).toContain('/compare/v1.2.3...v1.3.0)') }) + it('uses custom section headings in the PR body', async () => { + process.env.SECTIONS = 'feat: :rocket: Features' + await main() + expect(prBody()).toContain('### :rocket: Features') + expect(prBody()).not.toContain('### 🚀 Enhancements') + }) + + it('fails on an invalid sections input before writing anything', async () => { + process.env.SECTIONS = 'feature: Features' + await expect(main()).rejects.toThrow('unknown type `feature`') + expect(calls.some(c => c.method !== 'GET')).toBe(false) + }) + it('uses a custom title for the PR and the release commit', async () => { process.env.TITLE = 'chore(release): v{version}' await main() @@ -1113,6 +1127,13 @@ describe('independent main', () => { expect(commit.body).toMatchObject({ message: 'chore(release): 2 packages' }) }) + it('uses custom section headings in each package changelog', async () => { + process.env.SECTIONS = 'feat: :rocket: Features' + await main() + expect(prBody()).toContain('### :rocket: Features') + expect(prBody()).not.toContain('🚀 Enhancements') + }) + it('rejects a lockstep-only title placeholder', async () => { process.env.TITLE = 'v{version}' await expect(main()).rejects.toThrow('Unknown placeholder `{version}` in the `title` input; expected `{count}`, `{packages}`.') diff --git a/test/update-changelog.test.ts b/test/update-changelog.test.ts index 9926832..7ba6b2b 100644 --- a/test/update-changelog.test.ts +++ b/test/update-changelog.test.ts @@ -3,7 +3,7 @@ import { tmpdir } from 'node:os' import { resolve } from 'node:path' import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' -import { resolvePinnedVersion, setPrNotes, stripPlaceholderTimetable, stripPrNotes, TIMETABLE_PLACEHOLDER, buildBumpFileSet, dropRevertedCommits, buildIndependentBody, determineBump, formatChangelog, buildIndependentBumpFileSet, computeIndependentPlan, extractPreamble, truncateBody, dropAlreadyReleased, incVersion, latestLockstepTag, latestTagForPackage, releaseBranchDrift, isSupersededReleaseBranch, type Commit } from '../scripts/update-changelog.ts' +import { parseSectionsInput, resolvePinnedVersion, setPrNotes, stripPlaceholderTimetable, stripPrNotes, TIMETABLE_PLACEHOLDER, buildBumpFileSet, dropRevertedCommits, buildIndependentBody, determineBump, formatChangelog, buildIndependentBumpFileSet, computeIndependentPlan, extractPreamble, truncateBody, dropAlreadyReleased, incVersion, latestLockstepTag, latestTagForPackage, releaseBranchDrift, isSupersededReleaseBranch, type Commit } from '../scripts/update-changelog.ts' import { resolveWorkspaces } from '../scripts/_workspaces.ts' let tmp: string @@ -954,6 +954,38 @@ describe('determineBump', () => { expect(changelog).toContain('- ⚠️ new thing') expect(changelog).not.toContain('not a known type') }) + + it('renders custom section headings and keeps the default order', () => { + const changelog = formatChangelog( + [commit({ type: 'fix', description: 'a fix' }), commit({ type: 'feat', description: 'a feature' })], + { owner: 'owner', repo: 'repo', fromRef: null, toRef: 'main', titles: parseSectionsInput('feat: :rocket: Features\nfix: :bug: Bug Fixes') }, + ) + expect(changelog).toContain('### :rocket: Features') + expect(changelog).toContain('### :bug: Bug Fixes') + expect(changelog.indexOf(':rocket: Features')).toBeLessThan(changelog.indexOf(':bug: Bug Fixes')) + }) +}) + +describe('parseSectionsInput', () => { + it('returns the default headings for an empty input', () => { + expect(parseSectionsInput('')).toMatchObject({ feat: '🚀 Enhancements', fix: '🩹 Fixes' }) + }) + + it('overrides the listed types and keeps the others', () => { + const titles = parseSectionsInput('feat: :rocket: Features\r\n\n# a comment\n perf: Performance ') + expect(titles).toMatchObject({ feat: ':rocket: Features', perf: 'Performance', fix: '🩹 Fixes' }) + }) + + it('splits on the first colon only', () => { + expect(parseSectionsInput('docs: Docs: guides').docs).toBe('Docs: guides') + }) + + it('rejects malformed entries', () => { + expect(() => parseSectionsInput('feat Features')).toThrow('missing a colon') + expect(() => parseSectionsInput('feature: Features')).toThrow('unknown type `feature`') + expect(() => parseSectionsInput('feat:')).toThrow('empty title') + expect(() => parseSectionsInput('feat: A\nfeat: B')).toThrow('appears more than once') + }) }) describe('releaseBranchDrift', () => { From e926a9201826e9b04e89e0c4c79abcb23b80c3a9 Mon Sep 17 00:00:00 2001 From: Benjamin Canac <canacb1@gmail.com> Date: Wed, 18 Nov 2026 12:58:23 +0100 Subject: [PATCH 2/5] fix(pr): fall back per section and validate `sections` up front --- scripts/update-changelog.ts | 12 +++++++----- test/update-changelog-main.test.ts | 15 ++++++++++++++- test/update-changelog.test.ts | 9 +++++++++ 3 files changed, 30 insertions(+), 6 deletions(-) diff --git a/scripts/update-changelog.ts b/scripts/update-changelog.ts index 05d97c0..52c6109 100644 --- a/scripts/update-changelog.ts +++ b/scripts/update-changelog.ts @@ -545,8 +545,8 @@ export function formatChangelog ( * rendered line: the section heading already names the package. */ packageScopes?: string[] - /** Section headings by commit type, from `parseSectionsInput`. */ - titles?: Record<string, string> + /** Section headings by commit type, from `parseSectionsInput`. Missing types keep their default. */ + titles?: Partial<Record<string, string>> }, ): string { const grouped = new Map<string, Commit[]>() @@ -569,7 +569,7 @@ export function formatChangelog ( for (const type of Object.keys(TYPE_TITLES)) { const items = grouped.get(type) if (!items?.length) continue - lines.push(`### ${(opts.titles ?? TYPE_TITLES)[type]}`, '') + lines.push(`### ${opts.titles?.[type] ?? TYPE_TITLES[type]}`, '') for (const c of items) { const ownScopes = c.scope.split(',').map(s => s.trim()).filter(Boolean) const redundant = ownScopes.length === 1 && Boolean(opts.packageScopes?.includes(ownScopes[0]!)) @@ -1248,7 +1248,7 @@ export function buildIndependentBody ( repo: string preamble: string contributors?: Contributor[] - titles?: Record<string, string> + titles?: Partial<Record<string, string>> }, ): string { const releasedNames = new Set(plan.releases.map(r => r.name)) @@ -1344,6 +1344,8 @@ export async function main () { return } + // Validate before the no-release return, so a typo fails on the push that introduced it. + const titles = parseSectionsInput(process.env.SECTIONS ?? '') const latestTag = getLatestTag() const commits = getCommitsSince(latestTag).filter(isReleaseWorthy) @@ -1400,7 +1402,7 @@ export async function main () { repo: repo.repo, fromRef: latestTag, toRef: `v${newVersion}`, - titles: parseSectionsInput(process.env.SECTIONS ?? ''), + titles, }) console.log(`Current: ${currentVersion} -> ${newVersion} (${bump}${pinned ? `, pinned on #${pinned.pr.number}` : ''})`) diff --git a/test/update-changelog-main.test.ts b/test/update-changelog-main.test.ts index 5bd4dcc..fdfa75c 100644 --- a/test/update-changelog-main.test.ts +++ b/test/update-changelog-main.test.ts @@ -300,6 +300,12 @@ describe('lockstep main', () => { expect(calls.some(c => c.method !== 'GET')).toBe(false) }) + it('fails on an invalid sections input even with nothing to release', async () => { + process.env.SECTIONS = 'feature: Features' + git.commits = [{ ...FEAT, subject: 'chore(deps): bump something' }] + await expect(main()).rejects.toThrow('unknown type `feature`') + }) + it('uses a custom title for the PR and the release commit', async () => { process.env.TITLE = 'chore(release): v{version}' await main() @@ -1129,8 +1135,15 @@ describe('independent main', () => { it('uses custom section headings in each package changelog', async () => { process.env.SECTIONS = 'feat: :rocket: Features' + git.commits = [ + { ...FEAT, subject: 'feat(a): add a thing (#7)' }, + { ...FEAT, hash: 'd'.repeat(40), short: 'ddddddd', subject: 'feat(b): add another thing (#8)' }, + ] + git.revList = [FEAT.hash, 'd'.repeat(40)] await main() - expect(prBody()).toContain('### :rocket: Features') + const [, a, b] = prBody().split(/^### [ab] \(/m) + expect(a).toContain('### :rocket: Features') + expect(b).toContain('### :rocket: Features') expect(prBody()).not.toContain('🚀 Enhancements') }) diff --git a/test/update-changelog.test.ts b/test/update-changelog.test.ts index 7ba6b2b..b56e212 100644 --- a/test/update-changelog.test.ts +++ b/test/update-changelog.test.ts @@ -964,6 +964,15 @@ describe('determineBump', () => { expect(changelog).toContain('### :bug: Bug Fixes') expect(changelog.indexOf(':rocket: Features')).toBeLessThan(changelog.indexOf(':bug: Bug Fixes')) }) + + it('falls back to the default heading for a type missing from titles', () => { + const changelog = formatChangelog( + [commit({ type: 'feat', description: 'a feature' }), commit({ type: 'fix', description: 'a fix' })], + { owner: 'owner', repo: 'repo', fromRef: null, toRef: 'main', titles: { feat: 'Features' } }, + ) + expect(changelog).toContain('### Features') + expect(changelog).toContain('### 🩹 Fixes') + }) }) describe('parseSectionsInput', () => { From 8e17f0082cad4adaf318015fc195a1068fa02129 Mon Sep 17 00:00:00 2001 From: Benjamin Canac <canacb1@gmail.com> Date: Wed, 18 Nov 2026 14:09:04 +0100 Subject: [PATCH 3/5] fix(pr): validate `sections` before the release merge check --- scripts/update-changelog.ts | 9 ++++----- test/update-changelog-main.test.ts | 6 ++++++ 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/scripts/update-changelog.ts b/scripts/update-changelog.ts index 52c6109..dcb7644 100644 --- a/scripts/update-changelog.ts +++ b/scripts/update-changelog.ts @@ -1322,6 +1322,8 @@ export async function main () { const dryRun = Boolean(process.env.DRY_RUN) const repo = getRepo() const baseBranch = getCurrentBranch() + // Validate before any early return, so a typo fails on the push that introduced it. + const titles = parseSectionsInput(process.env.SECTIONS ?? '') const headSha = git('rev-parse', 'HEAD') if (await isReleaseMergeCommit(repo, headSha)) { @@ -1340,12 +1342,10 @@ export async function main () { if (!monorepo) { throw new Error('`mode: independent` requires the `packages` input.') } - await runIndependent(packagesInput) + await runIndependent(packagesInput, titles) return } - // Validate before the no-release return, so a typo fails on the push that introduced it. - const titles = parseSectionsInput(process.env.SECTIONS ?? '') const latestTag = getLatestTag() const commits = getCommitsSince(latestTag).filter(isReleaseWorthy) @@ -1498,10 +1498,9 @@ export async function main () { await upsertReleasePR(repo, { currentPR, title, head: releaseBranch, base: baseBranch, body }) } -async function runIndependent (packagesInput: string): Promise<void> { +async function runIndependent (packagesInput: string, titles: Record<string, string>): Promise<void> { const workspaces = resolveWorkspaces(process.cwd(), packagesInput) const scopeOverrides = parseScopesInput(process.env.SCOPES ?? '') - const titles = parseSectionsInput(process.env.SECTIONS ?? '') const tags = getAllTags() const lockstepTag = latestLockstepTag(tags) diff --git a/test/update-changelog-main.test.ts b/test/update-changelog-main.test.ts index fdfa75c..d1debb1 100644 --- a/test/update-changelog-main.test.ts +++ b/test/update-changelog-main.test.ts @@ -300,6 +300,12 @@ describe('lockstep main', () => { expect(calls.some(c => c.method !== 'GET')).toBe(false) }) + it('fails on an invalid sections input on a release merge too', async () => { + process.env.SECTIONS = 'feature: Features' + api.prsForHead = [{ head: { ref: 'release/v1.2.3' }, merged_at: '2024-01-01T00:00:00Z' }] + await expect(main()).rejects.toThrow('unknown type `feature`') + }) + it('fails on an invalid sections input even with nothing to release', async () => { process.env.SECTIONS = 'feature: Features' git.commits = [{ ...FEAT, subject: 'chore(deps): bump something' }] From c35ec79d1204f6929a13935ed73da544ec9c7ebc Mon Sep 17 00:00:00 2001 From: Daniel Roe <daniel@roe.dev> Date: Wed, 18 Nov 2026 14:30:03 +0000 Subject: [PATCH 4/5] feat(pr): order sections and customise contributor headings via `sections` --- README.md | 2 +- pr/action.yml | 2 +- scripts/update-changelog.ts | 89 +++++++++++++++--------------- test/update-changelog-main.test.ts | 9 +++ test/update-changelog.test.ts | 85 ++++++++++++++++++---------- 5 files changed, 111 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index 74bb81f..df18ac3 100644 --- a/README.md +++ b/README.md @@ -179,7 +179,7 @@ All subactions take a `node-version` input (default `24`; uppt needs `--experime | `allow-forks` | `false` | By default the action skips on forks so they don't open release PRs of their own. | | `prerelease` | _(unset)_ | One-shot prerelease identifier (`beta`, `rc`, or a bare number). See [Prereleases](#prereleases). | | `title` | `v{version}` | Template for the release PR title and commit message, e.g. `chore(release): v{version}`. In [independent mode](#independent-versioning-experimental) the placeholders are `{count}` and `{packages}` (`package` or `packages`), and the default is `chore: release {count} {packages}`. | -| `sections` | _(unset)_ | Changelog section headings to override, one per line as `<type>: <title>`, e.g. `feat: 🚀 Features`. Types left out keep their default heading (`🚀 Enhancements`, `🩹 Fixes`, `🔥 Performance`, ...). | +| `sections` | _(unset)_ | Changelog section headings to override, one per line as `<type>: <title>`, e.g. `feat: 🚀 Features`. `<type>` is a commit type, `contributors` or `new-contributors`. Listed commit types render first, in the order given; the rest keep their default heading and order (`🚀 Enhancements`, `🔥 Performance`, `🩹 Fixes`, ...). Lines starting with `#` are comments; a `#` later in a line is part of the title. | | `pr-notes` | _(unset)_ | Markdown to show in the release PR body below the timetable, such as links to preview builds. `{base}` is replaced with the base branch and, outside [independent mode](#independent-versioning-experimental), `{version}` with the next version (e.g. `1.3.0`). See below. | uppt keeps `pr-notes` in a marked block of the release PR body, refreshes it on every run, and leaves it out of the GitHub release notes. For example, if [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new) runs on pushes to your base branches, you can point at the latest build of the base branch: diff --git a/pr/action.yml b/pr/action.yml index 2c5d99d..626d318 100644 --- a/pr/action.yml +++ b/pr/action.yml @@ -40,7 +40,7 @@ inputs: required: false default: '' sections: - description: 'Optional changelog section headings, one per line as `<type>: <title>` (e.g. `feat: 🚀 Features`). Types left out keep their default heading.' + description: 'Optional changelog section headings, one per line as `<type>: <title>` (e.g. `feat: 🚀 Features`). `<type>` is a commit type, `contributors` or `new-contributors`. Listed commit types render first, in the order given; the rest keep their default heading and order. Lines starting with `#` are comments; a `#` later in a line is part of the title.' required: false default: '' prerelease: diff --git a/scripts/update-changelog.ts b/scripts/update-changelog.ts index dcb7644..69983e9 100644 --- a/scripts/update-changelog.ts +++ b/scripts/update-changelog.ts @@ -29,7 +29,7 @@ // `{version}` in lockstep mode and `{count}` / // `{packages}` in independent mode // SECTIONS newline-separated "<type>: <title>" overrides for -// the changelog section headings +// the changelog section headings and order // PR_NOTES Markdown kept in a marked block of the release PR // preamble and refreshed on every run, with `{base}` // and, in lockstep mode, `{version}` @@ -83,16 +83,23 @@ const TYPE_TITLES: Record<string, string> = { const KNOWN_TYPES = new Set(Object.keys(TYPE_TITLES)) +const CONTRIBUTOR_TITLES = { + 'new-contributors': '🎉 New Contributors', + 'contributors': '❤️ Contributors', +} + +const SECTION_KEYS = [...KNOWN_TYPES, ...Object.keys(CONTRIBUTOR_TITLES)] + /** - * Parse a newline-separated `sections:` input into the changelog section - * headings, starting from the defaults. Each non-blank line takes the - * shape `<type>: <title>`, split on the first colon so the title can hold - * colons of its own (`feat: :rocket: Features`). Lines starting with `#` - * are comments. + * Parse a newline-separated `sections:` input into section heading + * overrides, keyed by commit type or by `contributors` / + * `new-contributors`, in the order they are listed. Each non-blank line + * takes the shape `<type>: <title>`, split on the first colon so the title + * can hold colons of its own (`feat: :rocket: Features`). Lines starting + * with `#` are comments. */ export function parseSectionsInput (raw: string): Record<string, string> { - const titles = { ...TYPE_TITLES } - const seen = new Set<string>() + const titles: Record<string, string> = {} const lines = raw.split(/\r?\n/) for (let i = 0; i < lines.length; i++) { const line = lines[i]!.trim() @@ -103,21 +110,36 @@ export function parseSectionsInput (raw: string): Record<string, string> { } const type = line.slice(0, colon).trim() const title = line.slice(colon + 1).trim() - if (!KNOWN_TYPES.has(type)) { - throw new Error(`\`sections\` entry on line ${i + 1} names an unknown type \`${type}\`. Expected one of ${[...KNOWN_TYPES].map(t => `\`${t}\``).join(', ')}.`) + if (!SECTION_KEYS.includes(type)) { + throw new Error(`\`sections\` entry on line ${i + 1} names an unknown type \`${type}\`. Expected one of ${SECTION_KEYS.map(t => `\`${t}\``).join(', ')}.`) } if (!title) { throw new Error(`\`sections\` entry for \`${type}\` has an empty title.`) } - if (seen.has(type)) { + if (Object.hasOwn(titles, type)) { throw new Error(`\`sections\` entry for \`${type}\` appears more than once.`) } - seen.add(type) titles[type] = title } return titles } +function contributorLines (contributors: Contributor[], titles: Record<string, string> = {}): string[] { + const lines: string[] = [] + const newContributors = contributors.filter(c => c.isFirstTime) + if (newContributors.length) { + lines.push(`### ${titles['new-contributors'] ?? CONTRIBUTOR_TITLES['new-contributors']}`, '', newContributors.map(c => `- ${c.name} (@${c.username})`).join('\n'), '') + } + lines.push( + `### ${titles.contributors ?? CONTRIBUTOR_TITLES.contributors}`, + '', + contributors.length + ? contributors.map(c => `- ${c.name} (@${c.username})`).join('\n') + : '_no contributors yet_', + ) + return lines +} + const isReleaseWorthy = (c: Commit) => KNOWN_TYPES.has(c.type) && !(c.type === 'chore' && c.scope === 'deps') @@ -545,8 +567,12 @@ export function formatChangelog ( * rendered line: the section heading already names the package. */ packageScopes?: string[] - /** Section headings by commit type, from `parseSectionsInput`. Missing types keep their default. */ - titles?: Partial<Record<string, string>> + /** + * Section heading overrides by commit type, from `parseSectionsInput`. + * Listed types render first in their listed order; the rest keep their + * default heading and order. + */ + titles?: Record<string, string> }, ): string { const grouped = new Map<string, Commit[]>() @@ -566,7 +592,8 @@ export function formatChangelog ( const commitUrl = (sha: string) => `https://github.com/${opts.owner}/${opts.repo}/commit/${sha}` - for (const type of Object.keys(TYPE_TITLES)) { + const order = new Set([...Object.keys(opts.titles ?? {}), ...KNOWN_TYPES]) + for (const type of order) { const items = grouped.get(type) if (!items?.length) continue lines.push(`### ${opts.titles?.[type] ?? TYPE_TITLES[type]}`, '') @@ -1248,7 +1275,7 @@ export function buildIndependentBody ( repo: string preamble: string contributors?: Contributor[] - titles?: Partial<Record<string, string>> + titles?: Record<string, string> }, ): string { const releasedNames = new Set(plan.releases.map(r => r.name)) @@ -1291,19 +1318,7 @@ export function buildIndependentBody ( lines.push('') } - if (opts.contributors) { - const newContributors = opts.contributors.filter(c => c.isFirstTime) - if (newContributors.length) { - lines.push('### 🎉 New Contributors', '', newContributors.map(c => `- ${c.name} (@${c.username})`).join('\n'), '') - } - lines.push( - '### ❤️ Contributors', - '', - opts.contributors.length - ? opts.contributors.map(c => `- ${c.name} (@${c.username})`).join('\n') - : '_no contributors yet_', - ) - } + if (opts.contributors) lines.push(...contributorLines(opts.contributors, opts.titles)) return lines.join('\n').trimEnd() } @@ -1322,7 +1337,6 @@ export async function main () { const dryRun = Boolean(process.env.DRY_RUN) const repo = getRepo() const baseBranch = getCurrentBranch() - // Validate before any early return, so a typo fails on the push that introduced it. const titles = parseSectionsInput(process.env.SECTIONS ?? '') const headSha = git('rev-parse', 'HEAD') @@ -1454,7 +1468,6 @@ export async function main () { // unauthenticated against public repos. We still benefit from a token // (5000 req/h vs 60), but don't require one for previews. const contributors = await getContributors(commits, repo, cutoff) - const newContributors = contributors.filter(c => c.isFirstTime) const currentPR = await findOpenPR(repo, releaseBranch) const intro = `> v${newVersion} is the next ${bump} release.` @@ -1473,20 +1486,8 @@ export async function main () { '## 👉 Changelog', '', changelog, - ...(newContributors.length - ? [ - '', - '### 🎉 New Contributors', - '', - newContributors.map(c => `- ${c.name} (@${c.username})`).join('\n'), - ] - : []), - '', - '### ❤️ Contributors', '', - contributors.length - ? contributors.map(c => `- ${c.name} (@${c.username})`).join('\n') - : '_no contributors yet_', + ...contributorLines(contributors, titles), ].join('\n') if (dryRun) { diff --git a/test/update-changelog-main.test.ts b/test/update-changelog-main.test.ts index d1debb1..e36824b 100644 --- a/test/update-changelog-main.test.ts +++ b/test/update-changelog-main.test.ts @@ -294,6 +294,15 @@ describe('lockstep main', () => { expect(prBody()).not.toContain('### 🚀 Enhancements') }) + it('uses custom contributor headings in the PR body', async () => { + git.tags = [] + process.env.SECTIONS = 'contributors: :green_heart: Contributors\nnew-contributors: :wave: New Contributors' + await main() + expect(prBody()).toContain('### :wave: New Contributors\n\n- Ada (@ada)') + expect(prBody()).toContain('### :green_heart: Contributors\n\n- Ada (@ada)') + expect(prBody()).not.toContain('❤️') + }) + it('fails on an invalid sections input before writing anything', async () => { process.env.SECTIONS = 'feature: Features' await expect(main()).rejects.toThrow('unknown type `feature`') diff --git a/test/update-changelog.test.ts b/test/update-changelog.test.ts index b56e212..02a7e82 100644 --- a/test/update-changelog.test.ts +++ b/test/update-changelog.test.ts @@ -828,6 +828,17 @@ describe('independent release PR', () => { expect(body).toContain('### ❤️ Contributors\n\n- Ada (@ada)\n- Grace (@grace)') }) + it('renders custom contributor headings', () => { + const body = buildIndependentBody(fontainePlan([commit('feat(fontaine): thing')]), { + ...bodyOpts, + contributors: [{ name: 'Ada', username: 'ada', isFirstTime: true }], + titles: parseSectionsInput('contributors: :green_heart: Contributors\nnew-contributors: :wave: New Contributors'), + }) + + expect(body).toContain('### :wave: New Contributors\n\n- Ada (@ada)') + expect(body).toContain('### :green_heart: Contributors\n\n- Ada (@ada)') + }) + it('commits exactly the released manifests, preserving formatting and skipping the root', () => { const files = buildIndependentBumpFileSet(fontainePlan([commit('feat(fontaine): thing')])) @@ -915,21 +926,23 @@ describe('independent release PR', () => { }) }) -describe('determineBump', () => { - function commit (overrides: Partial<Commit>): Commit { - return { - hash: 'a'.repeat(40), - shortHash: 'aaaaaaa', - message: 'chore: thing', - type: 'chore', - scope: '', - description: 'thing', - isBreaking: false, - author: { name: 'Test', email: 'test@example.com' }, - references: [], - ...overrides, - } +function commitWith (overrides: Partial<Commit>): Commit { + return { + hash: 'a'.repeat(40), + shortHash: 'aaaaaaa', + message: 'chore: thing', + type: 'chore', + scope: '', + description: 'thing', + isBreaking: false, + author: { name: 'Test', email: 'test@example.com' }, + references: [], + ...overrides, } +} + +describe('determineBump', () => { + const commit = commitWith it('bumps major for a breaking change', () => { expect(determineBump([commit({}), commit({ isBreaking: true })])).toBe('major') @@ -942,6 +955,10 @@ describe('determineBump', () => { it('bumps patch for anything else', () => { expect(determineBump([commit({ type: 'fix' })])).toBe('patch') }) +}) + +describe('formatChangelog', () => { + const commit = commitWith it('renders breaking changes with a warning marker and skips unknown types', () => { const changelog = formatChangelog( @@ -955,34 +972,42 @@ describe('determineBump', () => { expect(changelog).not.toContain('not a known type') }) - it('renders custom section headings and keeps the default order', () => { + it('renders listed sections first, in the listed order', () => { const changelog = formatChangelog( - [commit({ type: 'fix', description: 'a fix' }), commit({ type: 'feat', description: 'a feature' })], - { owner: 'owner', repo: 'repo', fromRef: null, toRef: 'main', titles: parseSectionsInput('feat: :rocket: Features\nfix: :bug: Bug Fixes') }, + [ + commit({ type: 'docs', description: 'some docs' }), + commit({ type: 'perf', description: 'a speedup' }), + commit({ type: 'fix', description: 'a fix' }), + commit({ type: 'feat', description: 'a feature' }), + ], + { owner: 'owner', repo: 'repo', fromRef: null, toRef: 'main', titles: parseSectionsInput('feat: :rocket: Features\nfix: :bug: Bug Fixes\nperf: :fire: Performances') }, ) - expect(changelog).toContain('### :rocket: Features') - expect(changelog).toContain('### :bug: Bug Fixes') - expect(changelog.indexOf(':rocket: Features')).toBeLessThan(changelog.indexOf(':bug: Bug Fixes')) + const headings = changelog.split('\n').filter(line => line.startsWith('### ')) + expect(headings).toEqual(['### :rocket: Features', '### :bug: Bug Fixes', '### :fire: Performances', '### 📖 Documentation']) }) - it('falls back to the default heading for a type missing from titles', () => { + it('keeps the default heading and order for types missing from titles', () => { const changelog = formatChangelog( - [commit({ type: 'feat', description: 'a feature' }), commit({ type: 'fix', description: 'a fix' })], - { owner: 'owner', repo: 'repo', fromRef: null, toRef: 'main', titles: { feat: 'Features' } }, + [commit({ type: 'fix', description: 'a fix' }), commit({ type: 'perf', description: 'a speedup' }), commit({ type: 'feat', description: 'a feature' })], + { owner: 'owner', repo: 'repo', fromRef: null, toRef: 'main', titles: { fix: 'Bug Fixes' } }, ) - expect(changelog).toContain('### Features') - expect(changelog).toContain('### 🩹 Fixes') + const headings = changelog.split('\n').filter(line => line.startsWith('### ')) + expect(headings).toEqual(['### Bug Fixes', '### 🚀 Enhancements', '### 🔥 Performance']) }) }) describe('parseSectionsInput', () => { - it('returns the default headings for an empty input', () => { - expect(parseSectionsInput('')).toMatchObject({ feat: '🚀 Enhancements', fix: '🩹 Fixes' }) + it('returns no overrides for an empty input', () => { + expect(parseSectionsInput('')).toEqual({}) + }) + + it('returns the listed overrides in order, skipping blank and comment lines', () => { + const titles = parseSectionsInput('perf: Performance \r\n\n# a comment\n feat: :rocket: Features\ncontributors: :green_heart: Contributors') + expect(Object.entries(titles)).toEqual([['perf', 'Performance'], ['feat', ':rocket: Features'], ['contributors', ':green_heart: Contributors']]) }) - it('overrides the listed types and keeps the others', () => { - const titles = parseSectionsInput('feat: :rocket: Features\r\n\n# a comment\n perf: Performance ') - expect(titles).toMatchObject({ feat: ':rocket: Features', perf: 'Performance', fix: '🩹 Fixes' }) + it('keeps a `#` inside a title', () => { + expect(parseSectionsInput('feat: C# Features').feat).toBe('C# Features') }) it('splits on the first colon only', () => { From 17e0e69c9f6b04a25a28f118c067bfd22abe1fbd Mon Sep 17 00:00:00 2001 From: Daniel Roe <daniel@roe.dev> Date: Wed, 18 Nov 2026 14:44:01 +0000 Subject: [PATCH 5/5] docs: list the types `sections` accepts --- README.md | 22 +++++++++++++++++++++- pr/action.yml | 2 +- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index df18ac3..ff25e14 100644 --- a/README.md +++ b/README.md @@ -179,7 +179,7 @@ All subactions take a `node-version` input (default `24`; uppt needs `--experime | `allow-forks` | `false` | By default the action skips on forks so they don't open release PRs of their own. | | `prerelease` | _(unset)_ | One-shot prerelease identifier (`beta`, `rc`, or a bare number). See [Prereleases](#prereleases). | | `title` | `v{version}` | Template for the release PR title and commit message, e.g. `chore(release): v{version}`. In [independent mode](#independent-versioning-experimental) the placeholders are `{count}` and `{packages}` (`package` or `packages`), and the default is `chore: release {count} {packages}`. | -| `sections` | _(unset)_ | Changelog section headings to override, one per line as `<type>: <title>`, e.g. `feat: 🚀 Features`. `<type>` is a commit type, `contributors` or `new-contributors`. Listed commit types render first, in the order given; the rest keep their default heading and order (`🚀 Enhancements`, `🔥 Performance`, `🩹 Fixes`, ...). Lines starting with `#` are comments; a `#` later in a line is part of the title. | +| `sections` | _(unset)_ | Changelog section headings to override, one per line as `<type>: <title>`, e.g. `feat: 🚀 Features`. Listed commit types render first, in the order given; the rest keep their default heading and order. Lines starting with `#` are comments; a `#` later in a line is part of the title. See below for the accepted types. | | `pr-notes` | _(unset)_ | Markdown to show in the release PR body below the timetable, such as links to preview builds. `{base}` is replaced with the base branch and, outside [independent mode](#independent-versioning-experimental), `{version}` with the next version (e.g. `1.3.0`). See below. | uppt keeps `pr-notes` in a marked block of the release PR body, refreshes it on every run, and leaves it out of the GitHub release notes. For example, if [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new) runs on pushes to your base branches, you can point at the latest build of the base branch: @@ -190,6 +190,26 @@ uppt keeps `pr-notes` in a marked block of the release PR body, refreshes it on pr-notes: | Try the latest `{base}` build: `npm i https://pkg.pr.new/<owner>/<repo>/<package>@{base}` ``` + +`sections` accepts these types, shown in their default order with their default headings. Any other type fails the run. + +| Type | Default heading | +| --- | --- | +| `feat` | 🚀 Enhancements | +| `perf` | 🔥 Performance | +| `fix` | 🩹 Fixes | +| `refactor` | 💅 Refactors | +| `docs` | 📖 Documentation | +| `build` | 📦 Build | +| `types` | 🌊 Types | +| `chore` | 🏡 Chore | +| `examples` | 🏀 Examples | +| `test` | ✅ Tests | +| `style` | 🎨 Styles | +| `ci` | 🤖 CI | +| `revert` | ⏪ Reverts | +| `new-contributors` | 🎉 New Contributors | +| `contributors` | ❤️ Contributors | </details> <details> diff --git a/pr/action.yml b/pr/action.yml index 626d318..4e1710e 100644 --- a/pr/action.yml +++ b/pr/action.yml @@ -40,7 +40,7 @@ inputs: required: false default: '' sections: - description: 'Optional changelog section headings, one per line as `<type>: <title>` (e.g. `feat: 🚀 Features`). `<type>` is a commit type, `contributors` or `new-contributors`. Listed commit types render first, in the order given; the rest keep their default heading and order. Lines starting with `#` are comments; a `#` later in a line is part of the title.' + description: 'Optional changelog section headings, one per line as `<type>: <title>` (e.g. `feat: 🚀 Features`). `<type>` is one of `feat`, `perf`, `fix`, `refactor`, `docs`, `build`, `types`, `chore`, `examples`, `test`, `style`, `ci`, `revert` (the default order), `contributors` or `new-contributors`. Listed commit types render first, in the order given; the rest keep their default heading and order. Lines starting with `#` are comments; a `#` later in a line is part of the title.' required: false default: '' prerelease: