diff --git a/.changeset/light-ads-grin.md b/.changeset/light-ads-grin.md
index acd18e09e..0774ccb68 100644
--- a/.changeset/light-ads-grin.md
+++ b/.changeset/light-ads-grin.md
@@ -2,4 +2,20 @@
 'astro': minor
 ---
 
-Replace collections API with new file-based routing support
+**[BREAKING]** Replace the Collections API with new file-based routing.
+
+This is a breaking change which impacts collections, pagination, and RSS support.
+Runtime warnings have been added to help you migrate old code to the new API.
+If you have trouble upgrading, reach out on https://astro.build/chat
+
+This change was made due to confusion around our Collection API, which many users found difficult to use. The new file-based routing approach should feel more familiar to anyone who has used Next.js or SvelteKit. 
+
+Documentation added: 
+- https://astro-docs-git-main-pikapkg.vercel.app/core-concepts/routing
+- https://astro-docs-git-main-pikapkg.vercel.app/guides/pagination
+- https://astro-docs-git-main-pikapkg.vercel.app/guides/rss
+- https://astro-docs-git-main-pikapkg.vercel.app/reference/api-reference#getstaticpaths
+
+
+
+