💄 Restyle release announcements with Components V2

- Matches Amy's current message style: icon header, a section per category, install links as buttons
- Breaking changes get their own section and are never trimmed
- Trims categories proportionally so long releases show both changes and fixes
- Drops the Discord template and the render options only it used

Author: SnaveSutit

.scripts/plugins/releaseNoteTemplates/discord_release_notes_template

@@ -10,25 +10,18 @@
  * `DISCORD_ROLE_MINOR`, `DISCORD_ROLE_PATCH`, `DISCORD_ROLE_BREAKING`.
  */
 import { readFileSync } from 'node:fs'
+import { buildAnnouncement } from './announcement'
 import {
 	type Changelog,
 	type ReleasePing,
 	getChangelogEntry,
 	getReleasePings,
-	getReleaseUrl,
-	renderReleaseNotes,
 } from './releaseNotes'
 
 const DISCORD_API = 'https://discord.com/api/v10'
 const USER_AGENT = 'DiscordBot (https://github.com/Animated-Java/animated-java, 1.0)'
-const TEMPLATE_PATH = './.scripts/plugins/releaseNoteTemplates/discord_release_notes_template'
 const CHANGELOG_PATH = './src/pluginPackage/changelog.json'
 const IS_COMPONENTS_V2 = 1 << 15
-// Shared by every text display in a Components V2 message.
-const MAX_TEXT_LENGTH = 4000
-const ACCENT_COLOR = 0x00aced
-const BREAKING_LABEL =
-	'<:BreakingEmoji0:1432852678903463976><:BreakingEmoji1:1432852680404893818><:BreakingEmoji2:1432852682091270144><:BreakingEmoji3:1432852683534110790>'
 const ROLE_ENV_VARS: Record<ReleasePing, string> = {
 	prerelease: 'DISCORD_ROLE_PRERELEASE',
 	minor: 'DISCORD_ROLE_MINOR',
@@ -69,35 +62,11 @@ async function main() {
 	const changelog = JSON.parse(readFileSync(CHANGELOG_PATH, 'utf-8')) as Changelog
 	const entry = getChangelogEntry(changelog, version)
 	const roleIds = getReleasePings(version, entry).map(ping => requireEnv(ROLE_ENV_VARS[ping]))
-	const notes = renderReleaseNotes(readFileSync(TEMPLATE_PATH, 'utf-8'), version, entry, {
-		vars: { pings: roleIds.map(id => `<@&${id}>`).join(' ') },
-		maxLength: MAX_TEXT_LENGTH,
-		breakingLabel: BREAKING_LABEL,
-	})
 
 	const message = await discordPost(`/channels/${channelId}/messages`, {
 		flags: IS_COMPONENTS_V2,
 		allowed_mentions: { parse: [], roles: live ? roleIds : [] },
-		components: [
-			{
-				type: 17, // Container
-				accent_color: ACCENT_COLOR,
-				components: [
-					{ type: 10, content: notes }, // Text Display
-					{
-						type: 1, // Action Row
-						components: [
-							{
-								type: 2,
-								style: 5,
-								label: 'View on GitHub',
-								url: getReleaseUrl(version),
-							},
-						],
-					},
-				],
-			},
-		],
+		components: buildAnnouncement(version, entry, roleIds),
 	})
 	console.log(`Posted v${version} announcement (message ${message.id}) to channel ${channelId}`)
 

.scripts/release/announce.ts

@@ -0,0 +1,157 @@
+import {
+	type ChangelogCategory,
+	type ChangelogEntry,
+	BREAKING_TAG,
+	getReleaseAssetUrl,
+	getReleaseType,
+	getReleaseUrl,
+} from './releaseNotes'
+
+// Shared by every Text Display in a Components V2 message.
+const MAX_TEXT_LENGTH = 4000
+
+const ANIMATED_JAVA_EMOJI = '<:AnimatedJava:1349340042379661392>'
+const ICON_URL =
+	'https://raw.githubusercontent.com/Animated-Java/animated-java/refs/heads/main/src/assets/icons/animated_java_fancy_icon_centered.png'
+const INSTALL_GUIDE_URL = 'https://animated-java.dev/docs/getting-started/installing'
+const BREAKING_TITLE = 'Breaking Changes'
+const RELEASE_TYPE_LABELS = {
+	prerelease: 'Pre-release',
+	minor: 'Minor release',
+	patch: 'Patch release',
+}
+const CATEGORY_EMOJI: Record<string, string> = {
+	[BREAKING_TITLE]: '⚠️',
+	Changes: '✨',
+	Fixes: '🐛',
+}
+
+function textDisplay(content: string) {
+	return { type: 10, content }
+}
+
+function largeSeparator() {
+	return { type: 14, spacing: 2 }
+}
+
+function linkButton(label: string, url: string) {
+	return { type: 2, style: 5, label, url }
+}
+
+function formatDate(date: string) {
+	return new Date(date).toLocaleDateString('en-US', { dateStyle: 'long', timeZone: 'UTC' })
+}
+
+function formatCategory({ title, list }: ChangelogCategory) {
+	const emoji = CATEGORY_EMOJI[title]
+	return `## ${emoji ? emoji + ' ' : ''}${title}\n` + list.map(item => '- ' + item).join('\n')
+}
+
+/** Moves every `[BREAKING]` item into its own category, placed first. */
+function splitBreaking(categories: ChangelogCategory[]): ChangelogCategory[] {
+	const breaking: string[] = []
+	const rest = categories.map(category => ({
+		title: category.title,
+		list: category.list.filter(item => {
+			if (!item.includes(BREAKING_TAG)) return true
+			breaking.push(item.replaceAll(BREAKING_TAG, '').trim())
+			return false
+		}),
+	}))
+	return [{ title: BREAKING_TITLE, list: breaking }, ...rest]
+}
+
+/**
+ * Picks the category to drop an item from: the one keeping the largest share of its original
+ * items, so every category shrinks proportionally. Ties go to the later category. Index 0 holds the
+ * breaking changes, which are never dropped. Returns -1 when nothing is left to drop.
+ */
+function pickCategoryToTrim(categories: ChangelogCategory[], originalLengths: number[]) {
+	let picked = -1
+	let pickedShare = 0
+	for (let i = 1; i < categories.length; i++) {
+		const share = categories[i].list.length / originalLengths[i]
+		if (share > 0 && share >= pickedShare) {
+			picked = i
+			pickedShare = share
+		}
+	}
+	return picked
+}
+
+/**
+ * Formats each non-empty category as its own section, dropping items from the ends of categories
+ * until they fit in `budget` characters.
+ */
+function formatCategories(version: string, categories: ChangelogCategory[], budget: number) {
+	const originalLengths = categories.map(category => category.list.length)
+	categories = categories.map(category => ({ ...category, list: [...category.list] }))
+	let dropped = 0
+	for (;;) {
+		const sections = categories.filter(category => category.list.length > 0).map(formatCategory)
+		if (dropped > 0) {
+			sections[sections.length - 1] +=
+				`\n-# …plus ${dropped} more in the [full release notes](${getReleaseUrl(version)})`
+		}
+		if (sections.join('').length <= budget) return sections
+
+		const index = pickCategoryToTrim(categories, originalLengths)
+		if (index === -1) {
+			throw new Error(
+				`Release notes for ${version} don't fit in ${MAX_TEXT_LENGTH} characters, even with every non-breaking item removed`
+			)
+		}
+		categories[index].list.pop()
+		dropped++
+	}
+}
+
+/**
+ * Builds a release announcement as Components V2, in the style of the Animated Java Discord bot's
+ * messages: a header with the icon, a section per changelog category, then install links.
+ */
+export function buildAnnouncement(version: string, entry: ChangelogEntry, roleIds: string[]) {
+	const header = textDisplay(
+		`# ${ANIMATED_JAVA_EMOJI} Animated Java v${version}\n` +
+			`-# ${RELEASE_TYPE_LABELS[getReleaseType(version)]} · ${formatDate(entry.date)}`
+	)
+	const install = textDisplay(
+		'## 📦 How to Install\n' +
+			"New releases take a while to reach Blockbench's plugin list, so to get this one right away, " +
+			`download \`animated_java.js\` directly or [install it via URL](${INSTALL_GUIDE_URL}#advanced-installation-url).`
+	)
+	const footer = roleIds.length
+		? [textDisplay('-# ' + roleIds.map(id => `<@&${id}>`).join(' '))]
+		: []
+
+	const fixedLength = [header, install, ...footer].map(c => c.content).join('').length
+	const sections = formatCategories(
+		version,
+		splitBreaking(entry.categories),
+		MAX_TEXT_LENGTH - fixedLength
+	)
+
+	return [
+		{
+			type: 9, // Section
+			components: [header],
+			accessory: { type: 11, media: { url: ICON_URL } }, // Thumbnail
+		},
+		largeSeparator(),
+		...sections.map(textDisplay),
+		largeSeparator(),
+		{
+			type: 9, // Section
+			components: [install],
+			accessory: linkButton('Download', getReleaseAssetUrl(version, 'animated_java.js')),
+		},
+		{
+			type: 1, // Action Row
+			components: [
+				linkButton('View on GitHub', getReleaseUrl(version)),
+				linkButton('Installation Guide', INSTALL_GUIDE_URL),
+			],
+		},
+		...footer,
+	]
+}

.scripts/release/announcement.ts

@@ -12,50 +12,43 @@ export interface ChangelogEntry {
 
 export type Changelog = Record<string, ChangelogEntry>
 
-export type ReleasePing = 'prerelease' | 'minor' | 'patch' | 'breaking'
+export type ReleaseType = 'prerelease' | 'minor' | 'patch'
+export type ReleasePing = ReleaseType | 'breaking'
 
-export interface RenderOptions {
-	/** Extra `{name}` template variables, such as `pings`. */
-	vars?: Record<string, string>
-	/** Drop changelog items from the end until the notes fit, noting that some were cut. */
-	maxLength?: number
-	/** Replaces `[BREAKING]` in changelog items. */
-	breakingLabel?: string
-}
+export const BREAKING_TAG = '[BREAKING]'
 
 const REPO_URL = 'https://github.com/Animated-Java/animated-java'
-const BREAKING_TAG = '[BREAKING]'
-const DEFAULT_BREAKING_LABEL = '⚠️ **BREAKING** —'
-const ESCAPE_URLS_MARKER = '[[ESCAPE_URLS]]'
+const BREAKING_LABEL = '⚠️ **BREAKING** —'
 const VERSION_REGEX = /^(\d+)\.(\d+)\.(\d+)(-.+)?$/
-// Skips URLs already wrapped in <>, so they aren't escaped twice.
-const URL_REGEX =
-	/(?<!<)https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9]{1,6}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*)/gm
 
 export function getReleaseUrl(version: string) {
 	return `${REPO_URL}/releases/tag/v${version}`
 }
 
+export function getReleaseAssetUrl(version: string, fileName: string) {
+	return `${REPO_URL}/releases/download/v${version}/${fileName}`
+}
+
 export function getChangelogEntry(changelog: Changelog, version: string) {
 	const entry = changelog[version]
 	if (!entry) throw new Error(`No changelog entry found for version ${version}`)
 	return entry
 }
 
+export function getReleaseType(version: string): ReleaseType {
+	const match = VERSION_REGEX.exec(version)
+	if (!match) throw new Error(`Invalid version "${version}"`)
+	const [, , , patch, prerelease] = match
+	if (prerelease) return 'prerelease'
+	return patch === '0' ? 'minor' : 'patch'
+}
+
 /**
  * Picks which Discord roles to ping for a release: one for the release type, plus `breaking` if any
  * changelog item is tagged `[BREAKING]`.
  */
 export function getReleasePings(version: string, entry: ChangelogEntry) {
-	const match = VERSION_REGEX.exec(version)
-	if (!match) throw new Error(`Invalid version "${version}"`)
-	const [, , , patch, prerelease] = match
-
-	const pings: ReleasePing[] = []
-	if (prerelease) pings.push('prerelease')
-	else if (patch === '0') pings.push('minor')
-	else pings.push('patch')
-
+	const pings: ReleasePing[] = [getReleaseType(version)]
 	if (entry.categories.some(category => category.list.some(item => item.includes(BREAKING_TAG))))
 		pings.push('breaking')
 	return pings
@@ -65,69 +58,24 @@ function replaceTemplateVars(str: string, items: Record<string, string>) {
 	return str.replace(/\{(.+?)\}/g, str => items[str.replace(/[\{\}]/g, '')] ?? str)
 }
 
-function formatCategories(categories: ChangelogCategory[], breakingLabel: string) {
+function formatCategories(categories: ChangelogCategory[]) {
 	return categories
 		.filter(category => category.list.length > 0)
 		.map(
 			category =>
 				`### ${category.title}\n\n` +
 				category.list
-					.map(item => '- ' + item.replaceAll(BREAKING_TAG, breakingLabel))
+					.map(item => '- ' + item.replaceAll(BREAKING_TAG, BREAKING_LABEL))
 					.join('\n')
 		)
 		.join('\n\n')
 }
 
-/** Returns a copy of `categories` without its last item, or `undefined` if there are none left. */
-function dropLastItem(categories: ChangelogCategory[]) {
-	let index = categories.length - 1
-	while (index >= 0 && categories[index].list.length === 0) index--
-	if (index === -1) return
-	return categories.map((category, i) =>
-		i === index ? { ...category, list: category.list.slice(0, -1) } : category
-	)
-}
-
-export function renderReleaseNotes(
-	template: string,
-	version: string,
-	entry: ChangelogEntry,
-	options: RenderOptions = {}
-) {
-	const render = (categories: ChangelogCategory[], trimmed: boolean) => {
-		let formatted = formatCategories(
-			categories,
-			options.breakingLabel ?? DEFAULT_BREAKING_LABEL
-		)
-		if (trimmed) {
-			formatted += `\n\n-# …plus more in the [full release notes](${getReleaseUrl(version)})`
-		}
-		let content = replaceTemplateVars(template, {
-			...options.vars,
-			version,
-			release_url: getReleaseUrl(version),
-			categories: formatted,
-		})
-		if (content.includes(ESCAPE_URLS_MARKER)) {
-			content = content
-				.replace(ESCAPE_URLS_MARKER, '')
-				.replaceAll(URL_REGEX, match => `<${match}>`)
-		}
-		return content.trim() + '\n'
-	}
-
-	let categories: ChangelogCategory[] | undefined = entry.categories
-	let notes = render(categories, false)
-	if (options.maxLength === undefined) return notes
-
-	while (notes.length > options.maxLength) {
-		categories = dropLastItem(categories)
-		if (!categories) {
-			throw new Error(
-				`Release notes for ${version} don't fit in ${options.maxLength} characters, even with every changelog item removed`
-			)
-		}
-		notes = render(categories, true)
-	}
-	return notes
+export function renderReleaseNotes(template: string, version: string, entry: ChangelogEntry) {
+	const content = replaceTemplateVars(template, {
+		version,
+		release_url: getReleaseUrl(version),
+		categories: formatCategories(entry.categories),
+	})
+	return content.trim() + '\n'
 }