From de02459232df67e6fb3aec7f7bbb06a7ab586d44 Mon Sep 17 00:00:00 2001
From: Kian <kian@kian.org.uk>
Date: Mon, 18 Nov 2024 17:31:52 +0000
Subject: [PATCH] [Docs Site] Move deprecations to new page, move date header
 on changelogs (#18246)

---
 src/pages/changelog/index.astro    | 93 ++++++++++++++++--------------
 src/pages/deprecations/index.astro | 34 +++++++++++
 src/util/changelogs.ts             |  7 +++
 3 files changed, 92 insertions(+), 42 deletions(-)
 create mode 100644 src/pages/deprecations/index.astro

diff --git a/src/pages/changelog/index.astro b/src/pages/changelog/index.astro
index 503e9ff7939299..0e276c6342eb1b 100644
--- a/src/pages/changelog/index.astro
+++ b/src/pages/changelog/index.astro
@@ -1,6 +1,6 @@
 ---
 import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
-import { Badge } from "~/components";
+import { Aside, Badge } from "~/components";
 import { marked } from "marked";
 import { getChangelogs } from "~/util/changelogs";
 
@@ -8,9 +8,11 @@ const { products, productAreas, changelogs } = await getChangelogs();
 ---
 
 <StarlightPage frontmatter={{ title: "Changelogs", template: "splash" }}>
-	<Badge text="Beta" variant="caution" size="medium" />
-	<br />
-	<br />
+	<Aside>
+		Looking for API deprecations? They can be found on our <a
+			href="/deprecations/">dedicated deprecations page.</a
+		>
+	</Aside>
 	<p id="productDescription">
 		Subscribe to all Changelog posts via <a href="/changelog/index.xml">RSS</a>.
 	</p>
@@ -44,43 +46,48 @@ const { products, productAreas, changelogs } = await getChangelogs();
 	</select>
 	{
 		changelogs.map(([date, entries]) => (
-			<div style="overflow-anchor: none;" data-date={date}>
-				<h2>{date}</h2>
-				{entries?.map((entry) => (
-					<div
-						data-product={entry.product.toLowerCase()}
-						data-productArea={entry.productAreaName.toLowerCase()}
-					>
-						<h3>
-							<a href={entry.link}>{entry.product}</a>
-						</h3>
-						{["WAF", "DDoS protection"].includes(entry.product) ? (
-							<p
-								set:html={marked.parse(
-									entry.scheduled
-										? "**" +
-												"Scheduled changes for " +
-												(entry.date ?? "") +
-												"**"
-										: "**" + (entry.date ?? "") + "**",
-								)}
-							/>
-						) : (
-							<p set:html={marked.parse("**" + (entry.title ?? "") + "**")} />
-						)}
-						{["WAF", "DDoS protection"].includes(entry.product) ? (
-							<p
-								set:html={marked.parse(
-									"For more details, refer to the [changelog page](" +
-										entry.link +
-										").",
-								)}
-							/>
-						) : (
-							<p set:html={marked.parse(entry.description ?? "")} />
-						)}
-					</div>
-				))}
+			<div class="md:grid md:grid-cols-[20%_80%]" data-date={date}>
+				<div>
+					<h2 class="text-nowrap">{date}</h2>
+				</div>
+				<div class="!mt-0">
+					{entries?.map((entry) => (
+						<div
+							data-product={entry.product.toLowerCase()}
+							data-productArea={entry.productAreaName.toLowerCase()}
+						>
+							<h3>
+								<a href={entry.link}>{entry.product}</a>
+							</h3>
+							{["WAF", "DDoS protection"].includes(entry.product) && (
+								<p
+									set:html={marked.parse(
+										entry.scheduled
+											? "**" +
+													"Scheduled changes for " +
+													(entry.date ?? "") +
+													"**"
+											: "**" + (entry.date ?? "") + "**",
+									)}
+								/>
+							)}
+							{entry.title && (
+								<p set:html={marked.parse("**" + (entry.title ?? "") + "**")} />
+							)}
+							{["WAF", "DDoS protection"].includes(entry.product) ? (
+								<p
+									set:html={marked.parse(
+										"For more details, refer to the [changelog page](" +
+											entry.link +
+											").",
+									)}
+								/>
+							) : (
+								<p set:html={marked.parse(entry.description ?? "")} />
+							)}
+						</div>
+					))}
+				</div>
 			</div>
 		))
 	}
@@ -94,7 +101,9 @@ const { products, productAreas, changelogs } = await getChangelogs();
 	);
 	const navHeightPx = Number(navHeightRem.split("rem")[0]) * 16 + 16;
 
-	const headers = document.querySelectorAll<HTMLElement>("[data-date] > h2");
+	const headers = document.querySelectorAll<HTMLElement>(
+		"[data-date] > div > h2",
+	);
 	headers.forEach(
 		(header) => new StickyHeader(header, { offset: 0 - navHeightPx }),
 	);
diff --git a/src/pages/deprecations/index.astro b/src/pages/deprecations/index.astro
new file mode 100644
index 00000000000000..0aee2ae896ec57
--- /dev/null
+++ b/src/pages/deprecations/index.astro
@@ -0,0 +1,34 @@
+---
+import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
+import { marked } from "marked";
+import { getChangelogs } from "~/util/changelogs";
+
+const { changelogs } = await getChangelogs({
+	deprecationsOnly: true,
+});
+---
+
+<StarlightPage frontmatter={{ title: "Deprecations", template: "splash" }}>
+	<p>
+		Unless otherwise noted, all dates refer to the release date of the change.
+	</p>
+	<br />
+	{
+		changelogs.map(([date, entries]) => (
+			<div>
+				<h2>{date}</h2>
+				{entries?.map((entry) => (
+					<div
+						data-product={entry.product.toLowerCase()}
+						data-productArea={entry.productAreaName.toLowerCase()}
+					>
+						<h3>
+							<a href={entry.link}>{entry.product}</a>
+						</h3>
+						<p set:html={marked.parse(entry.description ?? "")} />
+					</div>
+				))}
+			</div>
+		))
+	}
+</StarlightPage>
diff --git a/src/util/changelogs.ts b/src/util/changelogs.ts
index 8554d068643f4b..dbab19dc9965b1 100644
--- a/src/util/changelogs.ts
+++ b/src/util/changelogs.ts
@@ -5,6 +5,7 @@ import { type CollectionEntry } from "astro:content";
 export async function getChangelogs(opts?: {
 	filter?: Parameters<typeof getCollection<"changelogs">>[1];
 	wranglerOnly?: boolean;
+	deprecationsOnly?: boolean;
 }) {
 	let changelogs;
 
@@ -22,6 +23,12 @@ export async function getChangelogs(opts?: {
 		);
 	}
 
+	if (opts?.deprecationsOnly) {
+		changelogs = changelogs.filter((x) => x.id === "api-deprecations");
+	} else {
+		changelogs = changelogs.filter((x) => x.id !== "api-deprecations");
+	}
+
 	const products = [...new Set(changelogs.flatMap((x) => x.data.productName))];
 	const productAreas = [
 		...new Set(changelogs.flatMap((x) => x.data.productArea)),