Design Release Notes Automation - System Design | WinJob

Problem Statement: Release Notes Automation

Enterprise release notes automation (GitHub Releases, GitLab releases, semantic-release-class) turns git history into semver tags, changelogs, and customer communications. Interviewers expect conventional commits, idempotent publishers, review gates, and monorepo aggregation—not a manual Notion doc.

Problem framing

Ingest commits/PRs from GitHub, GitLab, or monorepo merges and classify changes
Bump semver (major/minor/patch) from conventional commits or explicit labels
Generate changelog in Keep a Changelog / GitHub Releases markdown
Publish to GitHub Releases, GitLab releases, docs site, Slack, and artifact tags

Design choices

Event-driven pipeline on merge to default branch—not manual copy/paste
Separate generation (deterministic) from publication (idempotent API calls)
Human review gate for customer-facing notes; auto-publish for internal only

Deep dive

semantic-release, release-please, and GitLab Release CLI converge on: parse commits → compute version → render notes → tag + publish. GitHub generates release notes from PR titles; enterprises need policy, multi-service alignment, and audit.

javaOne Dark Pro

1 public final class SemverBumpPolicy {
2   public String nextVersion(String current, boolean hasBreaking, boolean hasFeat) {
3     int[] parts = parseSemver(current);
4     if (hasBreaking) return (parts[0] + 1) + ".0.0";
5     if (hasFeat) return parts[0] + "." + (parts[1] + 1) + ".0";
6     return parts[0] + "." + parts[1] + "." + (parts[2] + 1);
7   }
8 }

pythonOne Dark Pro

1 from dataclasses import dataclass
2 import re
3  
4 CONVENTIONAL = re.compile(r"^(?P<type>\w+)(?P<breaking>!)?(?:\((?P<scope>\w+)\))?: (?P<summary>.+)")
5  
6 @dataclass
7 class ParsedCommit:
8     change_type: str
9     breaking: bool
10     scope: str | None
11     summary: str
12  
13 def parse_subject(subject: str) -> ParsedCommit | None:
14     match = CONVENTIONAL.match(subject.strip())
15     if not match:
16         return None
17     return ParsedCommit(
18         change_type=match.group("type"),
19         breaking=bool(match.group("breaking")),
20         scope=match.group("scope"),
21         summary=match.group("summary"),
22     )

typescriptOne Dark Pro

1 interface PublishRequest {
2   releaseId: string;
3   idempotencyKey: string;
4   targets: Array<"github" | "gitlab" | "slack">;
5 }
6  
7 export async function publishRelease(req: PublishRequest): Promise<{ status: "published" | "duplicate" }> {
8   const existing = await store.findByIdempotency(req.idempotencyKey);
9   if (existing) return { status: "duplicate" };
10   await adapters.dispatch(req);
11   return { status: "published" };
12 }

Interviewer positioning

Open with who reads release notes (customers, SREs, compliance) and release cadence—that drives automation vs review gates.

How to open this one

The framing that lands for release-notes automation is deriving human-readable notes from structured source-of-truth data — conventional commits, merged-PR labels, linked tickets — rather than hand-writing them. Lead with the pipeline (collect merged changes between two tags → classify by type → render per audience), and the failure story that proves it: a release ships with notes that miss a breaking change because the underlying commit data was unstructured. That shows you understand the value is a reliable, auditable changelog generated from facts, not prose nobody keeps current.

Key Highlights

•Webhook ingest with HMAC verification and deduplication
•Semver policy engine with breaking-change detection
•Adapter-based publish to GitHub, GitLab, Slack, registries

1	public final class SemverBumpPolicy {
2	public String nextVersion(String current, boolean hasBreaking, boolean hasFeat) {
3	int[] parts = parseSemver(current);
4	if (hasBreaking) return (parts[0] + 1) + ".0.0";
5	if (hasFeat) return parts[0] + "." + (parts[1] + 1) + ".0";
6	return parts[0] + "." + parts[1] + "." + (parts[2] + 1);
7	}
8	}

1	from dataclasses import dataclass
2	import re
3
4	CONVENTIONAL = re.compile(r"^(?P<type>\w+)(?P<breaking>!)?(?:\((?P<scope>\w+)\))?: (?P<summary>.+)")
5
6	@dataclass
7	class ParsedCommit:
8	change_type: str
9	breaking: bool
10	scope: str \| None
11	summary: str
12
13	def parse_subject(subject: str) -> ParsedCommit \| None:
14	match = CONVENTIONAL.match(subject.strip())
15	if not match:
16	return None
17	return ParsedCommit(
18	change_type=match.group("type"),
19	breaking=bool(match.group("breaking")),
20	scope=match.group("scope"),
21	summary=match.group("summary"),
22	)

1	interface PublishRequest {
2	releaseId: string;
3	idempotencyKey: string;
4	targets: Array<"github" \| "gitlab" \| "slack">;
5	}
6
7	export async function publishRelease(req: PublishRequest): Promise<{ status: "published" \| "duplicate" }> {
8	const existing = await store.findByIdempotency(req.idempotencyKey);
9	if (existing) return { status: "duplicate" };
10	await adapters.dispatch(req);
11	return { status: "published" };
12	}