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
31 changes: 31 additions & 0 deletions docs/src/content/docs/changelogs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"):
Expand Down
76 changes: 76 additions & 0 deletions src/utils/__tests__/changelog-extract.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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', () => {
Expand Down Expand Up @@ -427,3 +429,77 @@ Some hidden content here.
expect(result![0].nestedContent).toContain(' </details>');
});
});

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([]);
});
});
85 changes: 85 additions & 0 deletions src/utils/__tests__/changelog-generate.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
// ============================================================================
Expand Down Expand Up @@ -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({
Expand Down
56 changes: 48 additions & 8 deletions src/utils/changelog.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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;
}
Expand Down Expand Up @@ -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;
}

/**
Expand Down Expand Up @@ -1702,6 +1734,8 @@ export interface RawChangelogData {
categories: Map<string, CategoryWithPRs>;
/** 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;
}
Expand Down Expand Up @@ -2036,6 +2070,7 @@ function categorizeCommits(rawCommits: RawCommitInfo[]): RawChangelogResult {

const categories = new Map<string, CategoryWithPRs>();
const leftovers: Commit[] = [];
const releaseNotes: string[] = [];
const missing: RawCommitInfo[] = [];

// Track bump type for auto-versioning (lower priority value = higher bump)
Expand All @@ -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();
Expand Down Expand Up @@ -2151,6 +2187,7 @@ function categorizeCommits(rawCommits: RawCommitInfo[]): RawChangelogResult {
data: {
categories,
leftovers,
releaseNotes,
releaseConfig,
},
stats: {
Expand Down Expand Up @@ -2198,7 +2235,7 @@ async function serializeChangelog(
disablePRLinks = false,
summarize = true,
): Promise<string> {
const { categories, leftovers, releaseConfig } = rawData;
const { categories, leftovers, releaseNotes, releaseConfig } = rawData;

const changelogSections: string[] = [];
const summaryCategories: SummaryCategory[] = [];
Expand Down Expand Up @@ -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');
}

Expand Down
Loading