diff --git a/docs/src/content/docs/changelogs.md b/docs/src/content/docs/changelogs.md index 00da54a2..c1f6ee2c 100644 --- a/docs/src/content/docs/changelogs.md +++ b/docs/src/content/docs/changelogs.md @@ -194,6 +194,37 @@ of the PR title. If no such section is present, the PR title is used as usual. included in the changelog. Other sections (Description, Issues, etc.) are ignored. +5. **Release Notes**: A [GitHub alert](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) + (`> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, or `> [!CAUTION]`) + in the "Changelog Entry" section is a note for the whole release, not an entry. + Craft places it as-is right under the version heading, above the categories, + so it also appears in the GitHub release and the changelog preview: + + ```markdown + ### Changelog Entry + + > [!IMPORTANT] + > This release bundles Sentry CLI v3. Self-hosted users need Sentry 24.11.1 or newer. + + - Bump Sentry CLI to v3 + ``` + + This will generate: + + ```markdown + ## 3.6.0 + + > [!IMPORTANT] + > This release bundles Sentry CLI v3. Self-hosted users need Sentry 24.11.1 or newer. + + ### New Features + + - Bump Sentry CLI to v3 by @user in [#123](url) + ``` + + Notes from several PRs are all kept, newest PR first. Without bullets or + text next to the alert, the PR title is used as the entry. + ## Scope grouping Changes are automatically grouped by scope (e.g., `feat(api):` groups under "Api"): diff --git a/src/utils/__tests__/changelog-extract.test.ts b/src/utils/__tests__/changelog-extract.test.ts index c60a4889..494debf6 100644 --- a/src/utils/__tests__/changelog-extract.test.ts +++ b/src/utils/__tests__/changelog-extract.test.ts @@ -3,12 +3,14 @@ * - extractScope: Extracts scope from conventional commit titles * - formatScopeTitle: Formats scope for display * - extractChangelogEntry: Extracts custom changelog entries from PR bodies + * - extractReleaseNotes: Extracts GitHub alerts from PR bodies */ import { extractScope, formatScopeTitle, extractChangelogEntry, + extractReleaseNotes, } from '../changelog'; describe('extractScope', () => { @@ -427,3 +429,77 @@ Some hidden content here. expect(result![0].nestedContent).toContain(' '); }); }); + +describe('extractReleaseNotes', () => { + it('extracts GitHub alerts from the changelog entry section', () => { + const prBody = `### Description + +> [!NOTE] +> Not in the changelog entry section. + +### Changelog Entry + +> [!IMPORTANT] +> This release bundles Sentry CLI v3. +> Self-hosted users need Sentry 24.11.1 or newer. + +- Bump Sentry CLI to v3 + +> [!warning] +> Second note. + +### Issues`; + + expect(extractReleaseNotes(prBody)).toEqual([ + '> [!IMPORTANT]\n> This release bundles Sentry CLI v3.\n> Self-hosted users need Sentry 24.11.1 or newer.', + '> [!warning]\n> Second note.', + ]); + }); + + it('keeps alerts out of changelog entries', () => { + const prBody = `### Changelog Entry + +> [!CAUTION] +> Breaking change. + +- Bump Sentry CLI to v3`; + + expect(extractChangelogEntry(prBody)).toEqual([ + { text: 'Bump Sentry CLI to v3' }, + ]); + }); + + it('returns no entries when the section only has an alert', () => { + const prBody = `### Changelog Entry + +> [!TIP] +> Try the new option.`; + + expect(extractChangelogEntry(prBody)).toBeNull(); + expect(extractReleaseNotes(prBody)).toEqual([ + '> [!TIP]\n> Try the new option.', + ]); + }); + + it('ignores blockquotes that are not GitHub alerts', () => { + const prBody = `### Changelog Entry + +> Just a quote. + +> [!NOTE] with text on the marker line + +- Entry`; + + expect(extractReleaseNotes(prBody)).toEqual([]); + }); + + it('handles CRLF line endings', () => { + const prBody = '### Changelog Entry\r\n\r\n> [!NOTE]\r\n> Hi\r\n'; + expect(extractReleaseNotes(prBody)).toEqual(['> [!NOTE]\n> Hi']); + }); + + it('returns an empty list without a changelog entry section', () => { + expect(extractReleaseNotes(null)).toEqual([]); + expect(extractReleaseNotes('> [!NOTE]\n> Hi')).toEqual([]); + }); +}); diff --git a/src/utils/__tests__/changelog-generate.test.ts b/src/utils/__tests__/changelog-generate.test.ts index cd5df055..80770ad5 100644 --- a/src/utils/__tests__/changelog-generate.test.ts +++ b/src/utils/__tests__/changelog-generate.test.ts @@ -1874,6 +1874,67 @@ changelog: }); }); + describe('release notes', () => { + it('places GitHub alerts above the categories', async () => { + setup( + [ + { + hash: 'abc123', + title: 'feat: Bump Sentry CLI to v3', + body: '', + pr: { + local: '1', + remote: { + number: '1', + author: { login: 'alice' }, + body: '## Changelog Entry\n\n> [!IMPORTANT]\n> Self-hosted users need Sentry 24.11.1 or newer.\n\n- Bump Sentry CLI to v3', + }, + }, + }, + { + hash: 'def456', + title: 'fix: Handle empty config', + body: '', + pr: { + local: '2', + remote: { + number: '2', + author: { login: 'bob' }, + body: '## Changelog Entry\n\n> [!NOTE]\n> Configs are validated now.', + }, + }, + }, + { + hash: 'ghi789', + title: 'chore: Internal cleanup', + body: '', + pr: { + local: '3', + remote: { + number: '3', + author: { login: 'carol' }, + body: '## Changelog Entry\n\n> [!WARNING]\n> Skipped PRs add no notes.', + labels: ['skip-changelog'], + }, + }, + }, + ], + null, + ); + const result = await generateChangesetFromGit(dummyGit, '1.0.0', 10); + expect(result.changelog).toBe( + [ + '> [!IMPORTANT]\n> Self-hosted users need Sentry 24.11.1 or newer.', + '> [!NOTE]\n> Configs are validated now.', + '### New Features ✨', + '- Bump Sentry CLI to v3 by @alice in [#1](https://github.com/test-owner/test-repo/pull/1)', + '### Bug Fixes 🐛', + '- Handle empty config by @bob in [#2](https://github.com/test-owner/test-repo/pull/2)', + ].join('\n\n'), + ); + }); + }); + // ============================================================================ // Revert commit handling tests // ============================================================================ @@ -2686,6 +2747,30 @@ describe('generateChangelogWithHighlight', () => { ); }); + it('shows release notes of the current PR without highlighting them', async () => { + setup({ + currentPR: { + number: 7, + title: 'feat: Bump Sentry CLI to v3', + body: '## Changelog Entry\n\n> [!IMPORTANT]\n> Self-hosted users need Sentry 24.11.1 or newer.', + author: 'alice', + }, + existingCommits: [{ hash: 'abc123', title: 'fix: Older fix', body: '' }], + }); + + const result = await generateChangelogWithHighlight(dummyGit, '1.0.0', 7); + + const note = + '> [!IMPORTANT]\n> Self-hosted users need Sentry 24.11.1 or newer.'; + expect(result.changelog.startsWith(`${note}\n\n`)).toBe(true); + expect(result.changelog).toContain( + '> - Bump Sentry CLI to v3 by **alice**', + ); + expect(result.prEntry).toBe( + `${note}\n\n### New Features ✨\n\n> - Bump Sentry CLI to v3 by **alice** in \`#7\``, + ); + }); + describe('revert handling in PR preview', () => { it('cancels out revert PR with its target commit', async () => { setup({ diff --git a/src/utils/changelog.ts b/src/utils/changelog.ts index 0e5058c9..1b34edbd 100644 --- a/src/utils/changelog.ts +++ b/src/utils/changelog.ts @@ -420,6 +420,8 @@ export interface ChangelogEntryItem { * - Multiple top-level bullets (-, *, +) become separate changelog entries * - Plain text (no bullets) becomes a single entry * - Nested bullets are preserved as nested content under their parent entry + * - GitHub alerts (`> [!NOTE]` etc.) are release notes, not entries; see + * {@link extractReleaseNotes} * - Only content within the "Changelog Entry" section is included * * @param prBody The PR description/body text @@ -428,6 +430,42 @@ export interface ChangelogEntryItem { export function extractChangelogEntry( prBody: string | null | undefined, ): ChangelogEntryItem[] | null { + const contentTokens = getChangelogEntryTokens(prBody); + return contentTokens ? parseTokensToEntries(contentTokens) : null; +} + +/** Matches the first line of a GitHub alert blockquote, such as `[!NOTE]` */ +const GITHUB_ALERT_PATTERN = + /^\[!(?:NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][ \t]*(?:\n|$)/i; + +/** + * Extracts the release notes from the "Changelog Entry" section of a PR + * description. A release note is a top-level GitHub alert blockquote, such as + * `> [!IMPORTANT]`. It belongs to the whole release, so it is placed under the + * version heading as-is instead of as a list item: GitHub does not render + * alerts inside lists. + * + * @param prBody The PR description/body text + * @returns The markdown of each alert in order, possibly empty + */ +export function extractReleaseNotes( + prBody: string | null | undefined, +): string[] { + return (getChangelogEntryTokens(prBody) ?? []) + .filter( + (token): token is Tokens.Blockquote => + token.type === 'blockquote' && GITHUB_ALERT_PATTERN.test(token.text), + ) + .map(token => token.raw.trim()); +} + +/** + * Returns the tokens of the "Changelog Entry" section of a PR description, or + * null if there is no such section or it is empty. + */ +function getChangelogEntryTokens( + prBody: string | null | undefined, +): Token[] | null { if (!prBody) { return null; } @@ -463,13 +501,7 @@ export function extractChangelogEntry( contentTokens.push(token); } - // If no content tokens, return null - if (contentTokens.length === 0) { - return null; - } - - // Process the content tokens into changelog entries - return parseTokensToEntries(contentTokens); + return contentTokens.length > 0 ? contentTokens : null; } /** @@ -1702,6 +1734,8 @@ export interface RawChangelogData { categories: Map; /** Commits that didn't match any category */ leftovers: Commit[]; + /** GitHub alerts from PR descriptions, placed above every category */ + releaseNotes: string[]; /** Release config for serialization */ releaseConfig: NormalizedReleaseConfig | null; } @@ -2036,6 +2070,7 @@ function categorizeCommits(rawCommits: RawCommitInfo[]): RawChangelogResult { const categories = new Map(); const leftovers: Commit[] = []; + const releaseNotes: string[] = []; const missing: RawCommitInfo[] = []; // Track bump type for auto-versioning (lower priority value = higher bump) @@ -2050,6 +2085,7 @@ function categorizeCommits(rawCommits: RawCommitInfo[]): RawChangelogResult { if (shouldExcludePR(labels, raw.author, releaseConfig, bodyToCheck)) { continue; } + releaseNotes.push(...extractReleaseNotes(raw.prBody)); // Use PR title if available, otherwise use commit title for pattern matching const titleForMatching = (raw.prTitle ?? raw.title).trim(); @@ -2151,6 +2187,7 @@ function categorizeCommits(rawCommits: RawCommitInfo[]): RawChangelogResult { data: { categories, leftovers, + releaseNotes, releaseConfig, }, stats: { @@ -2198,7 +2235,7 @@ async function serializeChangelog( disablePRLinks = false, summarize = true, ): Promise { - const { categories, leftovers, releaseConfig } = rawData; + const { categories, leftovers, releaseNotes, releaseConfig } = rawData; const changelogSections: string[] = []; const summaryCategories: SummaryCategory[] = []; @@ -2428,6 +2465,9 @@ async function serializeChangelog( if (summary.release) changelogSections.unshift(formatSummaryText(summary.release)); } + // Release notes go right under the version heading, as GitHub alerts only + // render outside lists. + changelogSections.unshift(...releaseNotes); return changelogSections.join('\n\n'); }