Skip to content

High performance self-hosted photo and video management solution.

feat: custom release notes (#32172)

Jason Rasmussenb620efba388b
diff --git a/.github/workflows/draft-release.yml b/.github/workflows/draft-release.yml
index a1193ad97f..4158875e2a 100644
--- a/.github/workflows/draft-release.yml
+++ b/.github/workflows/draft-release.yml
@@ -136,13 +136,16 @@ jobs:
name: release-apk-signed
github-token: ${{ steps.generate-token.outputs.token }}
- - name: Create draft release
+ - name: Setup Mise
+ uses: immich-app/devtools/actions/use-mise@06a9ef925332c91be647d6256642b86b398592c8 # use-mise-action-v3.2.1
+ with:
+ github_token: ${{ steps.generate-token.outputs.token }}
+
+ - name: Generate release notes
env:
GH_TOKEN: ${{ steps.generate-token.outputs.token }}
- REPO: ${{ github.repository }}
TAG: ${{ needs.tag.outputs.version }}
PRERELEASE: ${{ needs.tag.outputs.rc }}
- BRANCH: ${{ github.ref_name }}
run: |
tags=$(git -c versionsort.suffix=-rc tag --list 'v[0-9]*' --sort=-v:refname)
if [[ "${PRERELEASE}" != 'true' ]]; then
@@ -151,15 +154,24 @@ jobs:
previous=$(grep -A1 -xF "${TAG}" <<< "${tags}" | tail -1)
echo "generating notes from ${previous}"
+ mise //:notes --tag "${TAG}" --previous "${previous}" > "${RUNNER_TEMP}/notes.md"
+ cat "${RUNNER_TEMP}/notes.md"
+
+ - name: Create draft release
+ env:
+ GH_TOKEN: ${{ steps.generate-token.outputs.token }}
+ REPO: ${{ github.repository }}
+ TAG: ${{ needs.tag.outputs.version }}
+ PRERELEASE: ${{ needs.tag.outputs.rc }}
+ BRANCH: ${{ github.ref_name }}
+ run: |
gh release create "${TAG}" \
--repo "${REPO}" \
--target "${BRANCH}" \
--draft \
--verify-tag \
--prerelease="${PRERELEASE}" \
- --notes-file misc/release/notes.tmpl \
- --generate-notes \
- --notes-start-tag "${previous}" \
+ --notes-file "${RUNNER_TEMP}/notes.md" \
docker/docker-compose.yml \
docker/docker-compose.rootless.yml \
docker/example.env \
diff --git a/mise.toml b/mise.toml
index 63ab37d7cb..e4615e41d7 100644
--- a/mise.toml
+++ b/mise.toml
@@ -47,6 +47,13 @@ run = [
{ task = "//:open-api" },
]
+[tasks.notes]
+run = [
+ "pnpm --filter @immich/scripts install --frozen-lockfile",
+ "pnpm --filter @immich/scripts build",
+ "pnpm --filter @immich/scripts cli notes {{arg(name='args', var=true)}}",
+]
+
[tasks.plugins]
run = [
"pnpm --filter @immich/sdk --filter @immich/plugin-sdk --filter @immich/plugin-core install --frozen-lockfile",
diff --git a/packages/scripts/package.json b/packages/scripts/package.json
index a92375b380..ea428ae058 100644
--- a/packages/scripts/package.json
+++ b/packages/scripts/package.json
@@ -24,7 +24,8 @@
},
"dependencies": {
"commander": "^15.0.0",
- "semver": "^7.8.1"
+ "semver": "^7.8.1",
+ "yaml": "^2.9.1"
},
"devDependencies": {
"@types/node": "^24.13.6",
diff --git a/packages/scripts/src/cli.ts b/packages/scripts/src/cli.ts
index 95e50e9770..b8e71d7f95 100644
--- a/packages/scripts/src/cli.ts
+++ b/packages/scripts/src/cli.ts
@@ -1,4 +1,10 @@
import { Command, Option } from 'commander';
+import {
+ GitClient,
+ GitHubClient,
+ type NotesOptions,
+ NotesService,
+} from './commands/notes';
import { handleRelease } from './commands/release';
import {
RELEASE_TYPES,
@@ -43,5 +49,29 @@ export const cli = (argv: string[]) => {
}
});
+ program
+ .command('notes')
+ .description('generate release notes for a tag')
+ .requiredOption('-t, --tag <tag>', 'the tag being released')
+ .requiredOption('-p, --previous <tag>', 'the previously released tag')
+ .addOption(
+ new Option('--token <token>', 'a GitHub token')
+ .env('GH_TOKEN')
+ .default(process.env.GITHUB_TOKEN, 'GITHUB_TOKEN')
+ .makeOptionMandatory(),
+ )
+ .action(async ({ token, ...options }: NotesOptions & { token: string }) => {
+ try {
+ const service = new NotesService(
+ new GitClient(),
+ new GitHubClient(token),
+ );
+ process.stdout.write(await service.handleNotes(options));
+ } catch (error) {
+ console.error(error instanceof Error ? error.message : error);
+ process.exit(1);
+ }
+ });
+
return program.parse(argv);
};
diff --git a/packages/scripts/src/commands/notes.spec.ts b/packages/scripts/src/commands/notes.spec.ts
new file mode 100644
index 0000000000..fdc9b2c1dd
--- /dev/null
+++ b/packages/scripts/src/commands/notes.spec.ts
@@ -0,0 +1,243 @@
+import type { Public } from 'src/types.js';
+import { beforeEach, describe, expect, it, type Mocked, vi } from 'vitest';
+import {
+ type Contributor,
+ type GitClient,
+ type GitHubClient,
+ NotesService,
+ type PullRequest,
+} from './notes';
+
+type Fixture = Partial<PullRequest> & {
+ number: number;
+ original?: number;
+ published?: boolean;
+ commit?: boolean;
+ known?: boolean;
+};
+
+const alice = { login: 'alice', bot: false };
+const bob = { login: 'bob', bot: false };
+const bot = { login: 'immich-push-o-matic', bot: true };
+
+const link = (number: number) =>
+ `https://github.com/immich-app/immich/pull/${number}`;
+const fix = (number: number, author = alice) =>
+ `* fix: change ${number} by @${author.login}${author.bot ? '[bot]' : ''} in ${link(number)}`;
+
+const changelog = (...lines: string[]) =>
+ [
+ "## What's Changed",
+ ...lines,
+ '',
+ '**Full Changelog**: https://github.com/immich-app/immich/compare/v3.2.4...v3.3.0',
+ '',
+ ].join('\n');
+
+const body = (notes: string) => notes.slice(notes.indexOf("## What's Changed"));
+
+describe(NotesService.name, () => {
+ let git: Mocked<Public<GitClient>>;
+ let github: Mocked<Public<GitHubClient>>;
+ let sut: NotesService;
+
+ const setup = (fixtures: Fixture[], firstTimers: Contributor[] = []) => {
+ const pulls = new Map<number, PullRequest>();
+ const log = ['> chore: version v3.3.0'];
+
+ for (const {
+ original,
+ published,
+ commit = true,
+ known = true,
+ ...overrides
+ } of fixtures) {
+ const pull: PullRequest = {
+ title: `fix: change ${original ?? overrides.number}`,
+ body: original ? `Backport of #${original} to \`release/v3.2\`.` : null,
+ mergedAt: `2026-01-${String(overrides.number).padStart(2, '0')}T00:00:00Z`,
+ author: original ? bot : alice,
+ labels: original
+ ? ['changelog:bugfix', 'backport']
+ : ['changelog:bugfix'],
+ ...overrides,
+ };
+
+ if (known) {
+ pulls.set(pull.number, pull);
+ }
+
+ if (commit) {
+ log.push(`${published ? '<' : '>'} ${pull.title} (#${pull.number})`);
+ }
+ }
+
+ log.push('< chore: version v3.2.4');
+
+ git.log.mockReturnValue(log.join('\n') + '\n');
+ github.getPullRequests.mockImplementation(async (numbers) => {
+ const found = new Map<number, PullRequest>();
+ for (const number of numbers) {
+ const pull = pulls.get(number);
+ if (pull) {
+ found.set(number, pull);
+ }
+ }
+ return found;
+ });
+ github.getFirstTimers.mockResolvedValue(firstTimers);
+ };
+
+ const run = () => sut.handleNotes({ tag: 'v3.3.0', previous: 'v3.2.4' });
+
+ beforeEach(() => {
+ git = { log: vi.fn() };
+ github = { getPullRequests: vi.fn(), getFirstTimers: vi.fn() };
+ sut = new NotesService(git, github);
+ });
+
+ it('should compare the previous tag with the new tag', async () => {
+ setup([{ number: 1 }]);
+
+ await run();
+
+ expect(git.log).toHaveBeenCalledWith('v3.2.4', 'v3.3.0');
+ });
+
+ it('should start with the template and end with the full changelog', async () => {
+ setup([{ number: 1 }]);
+
+ const notes = await run();
+
+ expect(notes.startsWith('## Highlights')).toBe(true);
+ expect(body(notes)).toMatchInlineSnapshot(`
+ "## What's Changed
+ ### πŸ› Bug fixes
+ * fix: change 1 by @alice in https://github.com/immich-app/immich/pull/1
+
+ **Full Changelog**: https://github.com/immich-app/immich/compare/v3.2.4...v3.3.0
+ "
+ `);
+ });
+
+ it('should attribute a backport to the original pull request', async () => {
+ setup([
+ { number: 2, original: 1 },
+ { number: 1, commit: false },
+ ]);
+
+ const notes = await run();
+
+ expect(github.getPullRequests).toHaveBeenNthCalledWith(1, [2]);
+ expect(github.getPullRequests).toHaveBeenNthCalledWith(2, [1]);
+ expect(body(notes)).toBe(changelog('### πŸ› Bug fixes', fix(1)));
+ });
+
+ it('should fall back to the backport when the body lacks a reference', async () => {
+ setup([
+ { number: 2, original: 1, body: '* BACKPORT-CONFLICT' },
+ { number: 1, commit: false },
+ ]);
+
+ const notes = await run();
+
+ expect(body(notes)).toBe(
+ changelog(
+ '### πŸ› Bug fixes',
+ `* fix: change 1 by @immich-push-o-matic[bot] in ${link(2)}`,
+ ),
+ );
+ });
+
+ it('should drop main changes already published through a backport on the previous line', async () => {
+ setup([
+ { number: 3 },
+ { number: 1 },
+ { number: 2, original: 1, published: true },
+ ]);
+
+ const notes = await run();
+
+ expect(body(notes)).toBe(changelog('### πŸ› Bug fixes', fix(3)));
+ });
+
+ it('should drop changes backported to both lines when the previous line shipped first', async () => {
+ setup([
+ { number: 3, original: 1 },
+ { number: 4 },
+ { number: 2, original: 1, published: true },
+ { number: 1, commit: false },
+ ]);
+
+ const notes = await run();
+
+ expect(body(notes)).toBe(changelog('### πŸ› Bug fixes', fix(4)));
+ });
+
+ it('should list each original once in merge order', async () => {
+ setup([{ number: 6, original: 1 }, { number: 5 }, { number: 1 }]);
+
+ const notes = await run();
+
+ expect(body(notes)).toBe(changelog('### πŸ› Bug fixes', fix(1), fix(5)));
+ });
+
+ it('should ignore commits without a known pull request', async () => {
+ setup([{ number: 1 }, { number: 99, known: false }]);
+
+ const notes = await run();
+
+ expect(body(notes)).toBe(changelog('### πŸ› Bug fixes', fix(1)));
+ });
+
+ it('should group by changelog label and omit unlisted labels', async () => {
+ setup([
+ { number: 3, labels: ['πŸ—„οΈserver', 'changelog:bugfix'] },
+ { number: 2, labels: ['changelog:skip'] },
+ { number: 1, labels: ['changelog:feature'] },
+ ]);
+
+ const notes = await run();
+
+ expect(body(notes)).toBe(
+ changelog('### πŸš€ Features', fix(1), '### πŸ› Bug fixes', fix(3)),
+ );
+ });
+
+ it('should look up first contributions using the earliest change per human author', async () => {
+ setup([
+ { number: 4, author: bob },
+ { number: 3 },
+ { number: 2 },
+ { number: 1, author: bot },
+ ]);
+
+ await run();
+
+ expect(github.getFirstTimers).toHaveBeenCalledWith([
+ { author: alice, number: 2, mergedAt: '2026-01-02T00:00:00Z' },
+ { author: bob, number: 4, mergedAt: '2026-01-04T00:00:00Z' },
+ ]);
+ });
+
+ it('should render new contributors', async () => {
+ setup(
+ [{ number: 1 }],
+ [{ author: alice, number: 1, mergedAt: '2026-01-01T00:00:00Z' }],
+ );
+
+ const notes = await run();
+
+ expect(body(notes)).toMatchInlineSnapshot(`
+ "## What's Changed
+ ### πŸ› Bug fixes
+ * fix: change 1 by @alice in https://github.com/immich-app/immich/pull/1
+
+ ## New Contributors
+ * @alice made their first contribution in https://github.com/immich-app/immich/pull/1
+
+ **Full Changelog**: https://github.com/immich-app/immich/compare/v3.2.4...v3.3.0
+ "
+ `);
+ });
+});
diff --git a/packages/scripts/src/commands/notes.ts b/packages/scripts/src/commands/notes.ts
new file mode 100644
index 0000000000..dfc7e6fd7c
--- /dev/null
+++ b/packages/scripts/src/commands/notes.ts
@@ -0,0 +1,326 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { Public } from 'src/types.js';
+import { parse } from 'yaml';
+
+const findRoot = (dir: string): string =>
+ existsSync(join(dir, 'pnpm-workspace.yaml')) ? dir : findRoot(dirname(dir));
+
+const root = findRoot(dirname(fileURLToPath(import.meta.url)));
+
+const REPO = 'immich-app/immich';
+
+const Files = {
+ Config: join(root, '.github/release.yml'),
+ Template: join(root, 'misc/release/notes.tmpl'),
+};
+
+export type NotesOptions = {
+ tag: string;
+ previous: string;
+};
+
+type Side = 'left' | 'right';
+type Commit = { side: Side; number: number };
+
+type Author = { login: string; bot: boolean };
+export type PullRequest = {
+ number: number;
+ title: string;
+ body: string | null;
+ mergedAt: string;
+ author: Author;
+ labels: string[];
+};
+
+type Category = { title: string; labels: string[] };
+export type Contributor = { author: Author; number: number; mergedAt: string };
+
+type GraphQlResponse<T> = {
+ data?: T;
+ errors?: Array<{ message: string }>;
+};
+
+type PullRequestNode = {
+ number: number;
+ title: string;
+ body: string | null;
+ mergedAt: string;
+ author: { __typename: string; login: string } | null;
+ labels: { nodes: Array<{ name: string }> };
+};
+
+const PULL_REQUEST_BATCH = 50;
+const SEARCH_BATCH = 20;
+
+export class GitClient {
+ log(previous: string, tag: string) {
+ return execFileSync(
+ 'git',
+ [
+ 'log',
+ '--left-right',
+ '--no-merges',
+ '--format=%m %s',
+ `${previous}...${tag}`,
+ ],
+ { cwd: root, encoding: 'utf8' },
+ );
+ }
+}
+
+export class GitHubClient {
+ constructor(private token: string) {}
+
+ async getPullRequests(numbers: number[]) {
+ const pulls = new Map<number, PullRequest>();
+ const [owner, name] = REPO.split('/');
+
+ for (const batch of this.chunk(numbers, PULL_REQUEST_BATCH)) {
+ const fields = batch
+ .map(
+ (number) =>
+ `pr_${number}: pullRequest(number: ${number}) { ...PullRequestFields }`,
+ )
+ .join('\n');
+
+ const query = `
+ query($owner: String!, $name: String!) {
+ repository(owner: $owner, name: $name) { ${fields} }
+ }
+ fragment PullRequestFields on PullRequest {
+ number
+ title
+ body
+ mergedAt
+ author { __typename login }
+ labels(first: 100) { nodes { name } }
+ }`;
+
+ const data = await this.graphql<{
+ repository: Record<string, PullRequestNode | null>;
+ }>(query, { owner, name });
+
+ for (const node of Object.values(data.repository)) {
+ if (!node?.mergedAt) {
+ continue;
+ }
+
+ pulls.set(node.number, {
+ number: node.number,
+ title: node.title,
+ body: node.body,
+ mergedAt: node.mergedAt,
+ author: {
+ login: node.author?.login ?? 'ghost',
+ bot: node.author?.__typename === 'Bot',
+ },
+ labels: node.labels.nodes.map(({ name }) => name),
+ });
+ }
+ }
+
+ return pulls;
+ }
+
+ async getFirstTimers(candidates: Contributor[]) {
+ const firstTimers: Contributor[] = [];
+
+ for (const batch of this.chunk(candidates, SEARCH_BATCH)) {
+ const fields = batch
+ .map(({ author, mergedAt }, index) => {
+ const search = JSON.stringify(
+ `repo:${REPO} is:pr is:merged author:${author.login} merged:<${mergedAt}`,
+ );
+ return `c_${index}: search(query: ${search}, type: ISSUE, first: 1) { issueCount }`;
+ })
+ .join('\n');
+
+ const data = await this.graphql<Record<string, { issueCount: number }>>(
+ `query { ${fields} }`,
+ );
+
+ for (const [index, candidate] of batch.entries()) {
+ if (data[`c_${index}`].issueCount === 0) {
+ firstTimers.push(candidate);
+ }
+ }
+ }
+
+ return firstTimers;
+ }
+
+ private chunk<T>(items: T[], size: number) {
+ const chunks: T[][] = [];
+ for (let i = 0; i < items.length; i += size) {
+ chunks.push(items.slice(i, i + size));
+ }
+ return chunks;
+ }
+
+ private async graphql<T>(query: string, variables?: Record<string, string>) {
+ const response = await fetch('https://api.github.com/graphql', {
+ method: 'POST',
+ headers: {
+ Authorization: `Bearer ${this.token}`,
+ 'Content-Type': 'application/json',
+ },
+ body: JSON.stringify({ query, variables }),
+ });
+
+ if (!response.ok) {
+ throw new Error(
+ `GitHub GraphQL request failed: ${response.status} ${response.statusText}`,
+ );
+ }
+
+ const { data, errors } = (await response.json()) as GraphQlResponse<T>;
+ if (!data) {
+ throw new Error(
+ `GitHub GraphQL request failed: ${errors?.map(({ message }) => message).join(', ')}`,
+ );
+ }
+
+ return data;
+ }
+}
+
+export class NotesService {
+ constructor(
+ private git: Public<GitClient>,
+ private github: Public<GitHubClient>,
+ ) {}
+
+ async handleNotes({ tag, previous }: NotesOptions) {
+ const commits = this.parseCommits(this.git.log(previous, tag));
+ const pulls = await this.getPullRequests(commits);
+ const changes = this.selectChanges(commits, pulls);
+ const firstTimers = await this.getFirstTimers(changes);
+
+ return this.render({ tag, previous, changes, firstTimers });
+ }
+
+ private parseCommits(log: string): Commit[] {
+ return log.split('\n').flatMap((line) => {
+ const match = line.match(/^([<>]) .*\(#(\d+)\)$/);
+ return match
+ ? {
+ side: match[1] === '<' ? 'left' : 'right',
+ number: Number(match[2]),
+ }
+ : [];
+ });
+ }
+
+ private async getPullRequests(commits: Commit[]) {
+ const pulls = await this.github.getPullRequests(
+ this.unique(commits.map(({ number }) => number)),
+ );
+
+ const originals = this.unique(
+ [...pulls.values()].map((pull) => this.toOriginal(pull)),
+ ).filter((number) => !pulls.has(number));
+
+ for (const [number, pull] of await this.github.getPullRequests(originals)) {
+ pulls.set(number, pull);
+ }
+
+ return pulls;
+ }
+
+ private toOriginal(pull: PullRequest) {
+ const match = pull.body?.match(/^Backport of #(\d+) to `release\//);
+ return match ? Number(match[1]) : pull.number;
+ }
+
+ private selectChanges(commits: Commit[], pulls: Map<number, PullRequest>) {
+ const originals = (side: Side) =>
+ commits
+ .filter((commit) => commit.side === side)
+ .flatMap((commit) => pulls.get(commit.number) ?? [])
+ .map((pull) => this.toOriginal(pull));
+
+ const published = new Set(originals('left'));
+
+ return this.unique(originals('right'))
+ .filter((number) => !published.has(number))
+ .flatMap((number) => pulls.get(number) ?? [])
+ .sort((a, b) => a.mergedAt.localeCompare(b.mergedAt));
+ }
+
+ private getFirstTimers(changes: PullRequest[]) {
+ const candidates = new Map<string, Contributor>();
+
+ for (const { author, number, mergedAt } of changes) {
+ if (!author.bot && !candidates.has(author.login)) {
+ candidates.set(author.login, { author, number, mergedAt });
+ }
+ }
+
+ return this.github.getFirstTimers([...candidates.values()]);
+ }
+
+ private render({
+ tag,
+ previous,
+ changes,
+ firstTimers,
+ }: NotesOptions & { changes: PullRequest[]; firstTimers: Contributor[] }) {
+ const { changelog } = parse(readFileSync(Files.Config, 'utf8')) as {
+ changelog: { categories: Category[] };
+ };
+
+ const sections = [
+ readFileSync(Files.Template, 'utf8').trim(),
+ [
+ "## What's Changed",
+ ...changelog.categories.flatMap(({ title, labels }) => {
+ const matches = changes.filter((pull) =>
+ pull.labels.some((label) => labels.includes(label)),
+ );
+ return matches.length === 0
+ ? []
+ : [
+ `### ${title}`,
+ ...matches.map(
+ ({ title, author, number }) =>
+ `* ${title} by ${this.mention(author)} in ${this.link(number)}`,
+ ),
+ ];
+ }),
+ ].join('\n'),
+ ];
+
+ if (firstTimers.length > 0) {
+ sections.push(
+ [
+ '## New Contributors',
+ ...firstTimers.map(
+ ({ author, number }) =>
+ `* ${this.mention(author)} made their first contribution in ${this.link(number)}`,
+ ),
+ ].join('\n'),
+ );
+ }
+
+ sections.push(
+ `**Full Changelog**: https://github.com/${REPO}/compare/${previous}...${tag}`,
+ );
+
+ return sections.join('\n\n') + '\n';
+ }
+
+ private link(number: number) {
+ return `https://github.com/${REPO}/pull/${number}`;
+ }
+
+ private mention({ login, bot }: Author) {
+ return `@${login}${bot ? '[bot]' : ''}`;
+ }
+
+ private unique<T>(items: T[]) {
+ return [...new Set(items)];
+ }
+}
diff --git a/packages/scripts/src/types.ts b/packages/scripts/src/types.ts
index 586fdb8763..88866a86fc 100644
--- a/packages/scripts/src/types.ts
+++ b/packages/scripts/src/types.ts
@@ -41,6 +41,8 @@ export class JsonFile<T extends object> {
}
}
+export type Public<T extends object> = Pick<T, keyof T>;
+
export class ReleaseInputError extends Error {}
export class ReleaseError extends Error {
version: string;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0e9294acf6..53f48c1f51 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -372,6 +372,9 @@ importers:
semver:
specifier: ^7.8.1
version: 7.8.5
+ yaml:
+ specifier: ^2.9.1
+ version: 2.9.1
devDependencies:
'@types/node':
specifier: ^24.13.6