Add Changelog (#1487)

Author: samuelcolvin

docs-site/package-lock.json

@@ -10,9 +10,10 @@
   },
   "dependencies": {
     "@cloudflare/workers-types": "^4.20250129.0",
-    "typescript": "^5.7.3",
-    "wrangler": "^3.106.0",
+    "cookie": ">=0.7.0",
     "esbuild": ">=0.25.0",
-    "cookie": ">=0.7.0"
+    "marked": "^15.0.8",
+    "typescript": "^5.7.3",
+    "wrangler": "^3.106.0"
   }
 }

docs-site/package.json

@@ -1,8 +1,14 @@
+ import { marked } from 'marked'
+
 export default {
   async fetch(request, env): Promise<Response> {
+    const url = new URL(request.url)
+    if (url.pathname === '/changelog.html') {
+      const changelog = await getChangelog(env.KV, env.GIT_COMMIT_SHA)
+      return new Response(changelog, { headers: {'content-type': 'text/html'} })
+    }
     const r = await env.ASSETS.fetch(request)
     if (r.status == 404) {
-      const url = new URL(request.url)
       const redirectPath = redirect(url.pathname)
       if (redirectPath) {
         url.pathname = redirectPath
@@ -25,3 +31,55 @@ const redirect_lookup: Record<string, string> = {
 function redirect(pathname: string): string | null {
   return redirect_lookup[pathname.replace(/\/+$/, '')] ?? null
 }
+
+async function getChangelog(kv: KVNamespace, commitSha: string): Promise<string> {
+  const cache_key = `changelog:${commitSha}`
+  const cached = await kv.get(cache_key, {cacheTtl: 60})
+  if (cached) {
+    return cached
+  }
+  const headers = {
+    'X-GitHub-Api-Version': '2022-11-28',
+    'User-Agent': 'pydantic-ai-docs'
+  }
+  let url: string | undefined = 'https://api.github.com/repos/pydantic/pydantic-ai/releases'
+  const releases: Release[] = []
+  while (typeof url == 'string') {
+    const response = await fetch(url, { headers })
+    if (!response.ok) {
+      const text = await response.text()
+      throw new Error(`Failed to fetch changelog: ${response.status} ${response.statusText} ${text}`)
+    }
+    const newReleases = await response.json() as Release[]
+    releases.push(...newReleases)
+    const linkHeader = response.headers.get('link')
+    if (!linkHeader) {
+      break
+    }
+    url = linkHeader.match(/<([^>]+)>; rel="next"/)?.[1]
+  }
+  marked.use({pedantic: false, gfm: true})
+  const html = marked(releases.map(prepRelease).join('\n\n')) as string
+  await kv.put(cache_key, html, {expirationTtl: 300})
+  return html
+}
+
+interface Release {
+  name: string
+  body: string
+  html_url: string
+}
+
+function prepRelease(release: Release): string {
+  const body = release.body
+    .replace(/(#+)/g, (m) => `##${m}`)
+    .replace(/https:\/\/github.com\/pydantic\/pydantic-ai\/pull\/(\d+)/g, (url, id) => `[#${id}](${url})`)
+    .replace(/\*\*Full Changelog\*\*: (\S+)/, (_, url) => `[Compare diff](${url})`)
+  return `
+### ${release.name}
+
+${body}
+
+[View on GitHub](${release.html_url})
+`
+}

docs-site/src/index.ts

@@ -1,7 +1,7 @@
 // Generated by Wrangler by running `wrangler types worker-configuration.d.ts`
 
 interface Env {
-	VERSION_NOTICE_CACHE: KVNamespace;
+	KV: KVNamespace;
 	GIT_COMMIT_SHA: string;
 	GIT_BRANCH: string;
 	ASSETS: Fetcher;

docs-site/worker-configuration.d.ts

@@ -12,13 +12,13 @@ binding = "ASSETS"
 run_worker_first = true
 
 [[kv_namespaces]]
-binding = "VERSION_NOTICE_CACHE"
+binding = "KV"
 id = "4e49a275426244488a79d572da40eb69"
 
 [env.previews]
 workers_dev = true
 routes = []
 
 [[env.previews.kv_namespaces]]
-binding = "VERSION_NOTICE_CACHE"
+binding = "KV"
 id = "95eb127177234122896b4f0a80412f1b"

docs-site/wrangler.toml

@@ -0,0 +1,37 @@
+# Upgrade Guide
+
+PydanticAI is still pre-version 1, so breaking changes will occur, however:
+
+- We try to minimize them as much as possible.
+- We will use minor version bumps to signify breaking changes.
+- Wherever possible we'll deprecate old features so code continues to work with deprecation warnings when changing the public API.
+- We intend to release V1 in summer 2025, and then follow strict semantic versioning, e.g. no intentional breaking changes except in major versions.
+
+## Breaking Changes
+
+!!! note
+    Here's a filtered list of the breaking changes for each version to help you upgrade PydanticAI.
+
+### v0.1.0 2025-04-15
+
+See [#1248](https://github.com/pydantic/pydantic-ai/pull/1248) — the attribute/parameter name `result` was renamed to `output` in many places. Hopefully all changes keep a deprecated attribute or parameter with the old name, so you should get many deprecation warnings.
+
+See [#1484](https://github.com/pydantic/pydantic-ai/pull/1484) — `format_as_xml` was moved and made available to import from the package root, e.g. `from pydantic_ai import format_as_xml`.
+
+---
+
+## Full Changelog
+
+<div id="display-changelog">
+  For the full changelog, see <a href="https://github.com/pydantic/pydantic-ai/releases">GitHub Releases</a>.
+</div>
+
+<script>
+  async function getChangelog() {
+    const r = await fetch('/changelog.html');
+    if (r.ok) {
+      document.getElementById('display-changelog').innerHTML = await r.text();
+    }
+  }
+  getChangelog();
+</script>

docs/changelog.md

@@ -15,6 +15,7 @@ nav:
   - help.md
   - contributing.md
   - troubleshooting.md
+  - changelog.md
   - Documentation:
       - agents.md
       - Models: