From 0d1ed2191c101984506ebfab4b430ff1bb0b9b51 Mon Sep 17 00:00:00 2001
From: moonyue-w <300878504+moonyue-w@users.noreply.github.com>
Date: Wed, 23 Sep 2026 22:54:38 +0800
Subject: [PATCH 1/2] feat(release): publish reviewed changelog notes with each
 version

---
 .github/pull_request_template.md      |   1 +
 .github/scripts/release_notes.py      | 202 ++++++++++++++++++++++
 .github/scripts/test_release_notes.py | 234 ++++++++++++++++++++++++++
 .github/workflows/ci.yml              |  10 ++
 .github/workflows/release.yml         |  41 ++++-
 CHANGELOG.md                          |  13 ++
 CONTRIBUTING.md                       |  49 +++++-
 README.md                             |   2 +
 8 files changed, 549 insertions(+), 3 deletions(-)
 create mode 100644 .github/scripts/release_notes.py
 create mode 100644 .github/scripts/test_release_notes.py
 create mode 100644 CHANGELOG.md

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index c46b059..bd1293c 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -24,6 +24,7 @@ Commands and results:
 ## Impact
 
 - [ ] Public API or behavior changed
+- [ ] User-facing changes added to `CHANGELOG.md` under `Unreleased`, or not applicable (explain below)
 - [ ] Synchronous and asynchronous clients remain aligned
 - [ ] Generated API documentation updated
 - [ ] Contract fixtures updated
diff --git a/.github/scripts/release_notes.py b/.github/scripts/release_notes.py
new file mode 100644
index 0000000..7ebc22f
--- /dev/null
+++ b/.github/scripts/release_notes.py
@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""Validate changelogs and publish their approved version entry to GitHub."""
+
+import argparse
+import datetime
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+VERSION = r"[0-9][0-9A-Za-z.!+-]*"
+HEADING = re.compile(rf"## \[(Unreleased|{VERSION})\](?: - (\d{{4}}-\d{{2}}-\d{{2}}))?")
+
+
+def outside_fences(text):
+    fence = None
+    for line in text.splitlines():
+        marker = re.match(r"^\s{0,3}(`{3,}|~{3,})", line)
+        if fence:
+            if re.fullmatch(rf"\s{{0,3}}{re.escape(fence[0])}{{{len(fence)},}}\s*", line):
+                fence = None
+            yield ""
+        elif marker:
+            fence = marker[1]
+            yield ""
+        else:
+            yield line
+    if fence:
+        raise ValueError("Unclosed Markdown code fence")
+
+
+def validate_entry(version, body):
+    visible = "\n".join(outside_fences(body))
+    if re.search(r"\b(?:TODO|TBD)\b|<[^>]*(?:describe|placeholder)[^>]*>", visible, re.I):
+        raise ValueError(f"{version}: replace placeholder text with release notes")
+    items = re.findall(r"^\s*[-*] (.+)$", visible, re.M)
+    meaningful = [re.sub(r"[^\w]+", "", item).lower() for item in items]
+    if (
+        not meaningful
+        or not all(meaningful)
+        or any(item in {"placeholder", "pending", "comingsoon", "none", "na"} for item in meaningful)
+    ):
+        raise ValueError(f"{version}: add at least one substantive changelog bullet")
+
+
+def parse_changelog(text):
+    # Comments may guide authors but must not appear in the published notes.
+    text = re.sub(r"<!--.*?-->", "", text, flags=re.S)
+    if "<!--" in text or "-->" in text:
+        raise ValueError("Unclosed or unmatched Markdown comment")
+    sections = {}
+    current = None
+    for line, visible in zip(text.splitlines(), list(outside_fences(text))):
+        if re.match(r"^##(?:\s|$)", visible):
+            match = HEADING.fullmatch(line)
+            if not match:
+                raise ValueError(f"Expected '## [version]' or '## [version] - YYYY-MM-DD': {line}")
+            current, date = match.groups()
+            if current in sections:
+                raise ValueError(f"Duplicate changelog section: {current}")
+            if date:
+                datetime.date.fromisoformat(date)
+            if current == "Unreleased" and date:
+                raise ValueError("Unreleased must not have a release date")
+            sections[current] = []
+        elif current is not None:
+            sections[current].append(line)
+    if not sections or next(iter(sections)) != "Unreleased":
+        raise ValueError("The first version section must be '## [Unreleased]'")
+    entries = {version: "\n".join(lines).strip() + "\n" for version, lines in sections.items()}
+    for version, body in entries.items():
+        if version != "Unreleased" or body.strip():
+            validate_entry(version, body)
+    return entries
+
+
+def extract_notes(text, version):
+    if not re.fullmatch(VERSION, version):
+        raise ValueError("Use a version without the v prefix, not Unreleased")
+    entries = parse_changelog(text)
+    if version not in entries:
+        raise ValueError(f"CHANGELOG.md has no entry for {version}; include it in the release PR")
+    return entries[version]
+
+
+def existing_release(repository, tag):
+    url = f"https://api.github.com/repos/{repository}/releases/tags/{urllib.parse.quote(tag, safe='')}"
+    request = urllib.request.Request(
+        url,
+        headers={
+            "Authorization": f"Bearer {os.environ['GH_TOKEN']}",
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "sdk-release-notes",
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return json.load(response)
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            return None
+        raise
+
+
+def publish_notes(version, commit_sha, prerelease, notes):
+    repository = os.environ["GITHUB_REPOSITORY"]
+    if not re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repository):
+        raise ValueError("Invalid GITHUB_REPOSITORY")
+    if not re.fullmatch(r"[0-9a-f]{40}", commit_sha):
+        raise ValueError("commit_sha must be a full lowercase commit SHA")
+    tag = f"v{version}"
+
+    def git(*args):
+        return subprocess.check_output(["git", *args], text=True).strip()
+
+    if git("rev-parse", "HEAD") != commit_sha:
+        raise ValueError("Release notes must be read from the approved commit")
+    subprocess.run(["git", "fetch", "--force", "origin", f"refs/tags/{tag}:refs/tags/{tag}"], check=True)
+    if git("cat-file", "-t", f"refs/tags/{tag}") != "tag":
+        raise ValueError(f"{tag} must be an annotated release tag")
+    if git("rev-parse", f"refs/tags/{tag}^{{commit}}") != commit_sha:
+        raise ValueError(f"{tag} does not point to the approved commit")
+
+    existing = existing_release(repository, tag)
+    if existing is not None:
+        if (
+            existing.get("tag_name") != tag
+            or existing.get("name") != tag
+            or existing.get("draft") is not False
+            or existing.get("prerelease") is not prerelease
+            or (existing.get("body") or "").strip() != notes.strip()
+        ):
+            raise ValueError(f"Existing GitHub Release {tag} differs from the approved notes or metadata")
+        url = existing["html_url"]
+        print(f"Reusing GitHub Release: {url}")
+    else:
+        with tempfile.TemporaryDirectory() as directory:
+            notes_file = Path(directory) / "release-notes.md"
+            notes_file.write_text(notes, encoding="utf-8")
+            command = [
+                "gh",
+                "release",
+                "create",
+                tag,
+                "--repo",
+                repository,
+                "--verify-tag",
+                "--target",
+                commit_sha,
+                "--title",
+                tag,
+                "--notes-file",
+                str(notes_file),
+            ]
+            if prerelease:
+                command += ["--prerelease", "--latest=false"]
+            url = subprocess.check_output(command, text=True).strip()
+        print(f"Created GitHub Release: {url}")
+    if os.environ.get("GITHUB_STEP_SUMMARY"):
+        with open(os.environ["GITHUB_STEP_SUMMARY"], "a", encoding="utf-8") as summary:
+            summary.write(f"\nGitHub Release: {url}\n")
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("command", choices=["check", "extract", "publish"])
+    parser.add_argument("--changelog", type=Path, default=Path("CHANGELOG.md"))
+    parser.add_argument("--version")
+    parser.add_argument("--output", type=Path)
+    parser.add_argument("--commit-sha")
+    parser.add_argument("--prerelease", choices=["true", "false"])
+    args = parser.parse_args()
+    text = args.changelog.read_text(encoding="utf-8")
+    if args.command == "check":
+        parse_changelog(text)
+        print("Changelog is valid")
+        return
+    if not args.version:
+        parser.error("--version is required")
+    notes = extract_notes(text, args.version)
+    if args.command == "extract":
+        if args.output:
+            args.output.write_text(notes, encoding="utf-8")
+        else:
+            print(notes, end="")
+    else:
+        if not args.commit_sha or args.prerelease is None:
+            parser.error("publish requires --commit-sha and --prerelease")
+        publish_notes(args.version, args.commit_sha, args.prerelease == "true", notes)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (ValueError, KeyError, OSError, urllib.error.URLError, subprocess.CalledProcessError) as exc:
+        sys.exit(f"Release notes: {exc}")
diff --git a/.github/scripts/test_release_notes.py b/.github/scripts/test_release_notes.py
new file mode 100644
index 0000000..589b8cc
--- /dev/null
+++ b/.github/scripts/test_release_notes.py
@@ -0,0 +1,234 @@
+import io
+import os
+import subprocess
+import tempfile
+import unittest
+import urllib.error
+from pathlib import Path
+from unittest.mock import patch
+
+import release_notes as notes
+
+CHANGELOG = """# Changelog
+
+## [Unreleased]
+
+### Added
+- Forward: support the next API.
+
+## [0.2.0] - 2026-09-23
+
+### Fixed
+- Managed: preserve streamed events after reconnecting. (#42)
+
+### Migration
+- Replace the old option with `new_option`.
+
+```python
+## [0.1.0]
+client = Client(new_option=True)
+```
+
+## [0.1.0]
+
+### Added
+- Initial SDK clients.
+"""
+SHA = "a" * 40
+BODY = "### Fixed\n\n- Preserve streamed events.\n"
+URL = "https://github.com/example/sdk/releases/tag/v0.2.0"
+
+
+class ChangelogTests(unittest.TestCase):
+    def test_extracts_only_target_and_keeps_migration_code(self):
+        body = notes.extract_notes(CHANGELOG, "0.2.0")
+        self.assertIn("Managed: preserve streamed events", body)
+        self.assertIn("## [0.1.0]\nclient = Client", body)
+        self.assertNotIn("Initial SDK clients", body)
+        self.assertNotIn("support the next API", body)
+        self.assertNotIn("2026-09-23", body)
+
+    def test_empty_unreleased_and_optional_date(self):
+        entries = notes.parse_changelog("## [Unreleased]\n\n## [1.0.0]\n- Add clients.\n")
+        self.assertEqual(entries["1.0.0"], "- Add clients.\n")
+
+    def test_supports_each_ecosystems_canonical_version(self):
+        for version in ("0.2.0-rc.1", "0.2.0rc1", "0.2.0.dev1", "0.2.0.post1", "1!0.2.0"):
+            with self.subTest(version=version):
+                text = f"## [Unreleased]\n\n## [{version}]\n- Fix a regression.\n"
+                self.assertEqual(notes.extract_notes(text, version), "- Fix a regression.\n")
+
+    def test_rejects_missing_target_or_unreleased_request(self):
+        for version in ("0.3.0", "Unreleased", "v0.2.0", "0.2.0\n--help"):
+            with self.subTest(version=version), self.assertRaises(ValueError):
+                notes.extract_notes(CHANGELOG, version)
+
+    def test_rejects_duplicate_versions_and_unreleased(self):
+        for heading in ("0.2.0", "Unreleased"):
+            with self.subTest(heading=heading), self.assertRaisesRegex(ValueError, "Duplicate"):
+                notes.parse_changelog(CHANGELOG + f"\n## [{heading}]\n- Another note.\n")
+
+    def test_rejects_empty_and_placeholder_entries(self):
+        for body in (
+            "",
+            "### Fixed",
+            "<!-- - Fix a bug. -->",
+            "- TODO",
+            "- TBD: explain",
+            "- ...",
+            "- Pending",
+            "- <describe the change>",
+            "```\n- Only an example.\n```",
+            "- Real change.\n- TBD",
+        ):
+            with self.subTest(body=body), self.assertRaises(ValueError):
+                notes.parse_changelog(f"## [Unreleased]\n\n## [0.2.0]\n{body}\n")
+
+    def test_omits_author_comments(self):
+        body = notes.extract_notes(
+            CHANGELOG.replace("### Fixed", "<!-- TODO: private drafting hint -->\n### Fixed"), "0.2.0"
+        )
+        self.assertNotIn("TODO", body)
+
+    def test_rejects_bad_structure_and_dates(self):
+        for text in (
+            "## [0.2.0]\n- Fix a regression.",
+            "## [Unreleased]\n## 0.2.0\n- Fix a regression.",
+            "## [Unreleased] - 2026-09-23",
+            "## [Unreleased]\n## [0.2.0] - 2026-02-30\n- Fix a regression.",
+            "## [Unreleased]\n<!-- unfinished comment",
+            "## [Unreleased]\n```\nunclosed example",
+        ):
+            with self.subTest(text=text), self.assertRaises(ValueError):
+                notes.parse_changelog(text)
+
+    def test_cli_extract_and_missing_version_exit_status(self):
+        script = str(Path(notes.__file__).resolve())
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory)
+            (path / "CHANGELOG.md").write_text(CHANGELOG, encoding="utf-8")
+            command = [os.sys.executable, script, "extract", "--version"]
+            result = subprocess.run(
+                command + ["0.2.0", "--output", "notes.md"], cwd=path, capture_output=True, text=True
+            )
+            self.assertEqual(result.returncode, 0, result.stderr)
+            self.assertEqual((path / "notes.md").read_text(), notes.extract_notes(CHANGELOG, "0.2.0"))
+            result = subprocess.run(command + ["0.3.0"], cwd=path, capture_output=True, text=True)
+            self.assertNotEqual(result.returncode, 0)
+            self.assertIn("has no entry", result.stderr)
+
+
+class PublishTests(unittest.TestCase):
+    def setUp(self):
+        self.env = patch.dict(os.environ, {"GITHUB_REPOSITORY": "example/sdk", "GH_TOKEN": "test-token"})
+        self.env.start()
+        self.addCleanup(self.env.stop)
+        self.lookup = patch.object(notes, "existing_release", return_value=None).start()
+        self.run = patch.object(notes.subprocess, "run").start()
+        self.output = patch.object(notes.subprocess, "check_output", side_effect=self.command_output).start()
+        patch.dict(os.environ, {"GITHUB_STEP_SUMMARY": ""}).start()
+        self.addCleanup(patch.stopall)
+        self.created_notes = None
+
+    def command_output(self, command, **kwargs):
+        if command[0] == "gh":
+            self.created_notes = Path(command[command.index("--notes-file") + 1]).read_text()
+            return URL + "\n"
+        if command[1] == "cat-file":
+            return "tag\n"
+        return SHA + "\n"
+
+    def release(self, **changes):
+        return dict(tag_name="v0.2.0", name="v0.2.0", body=BODY, draft=False, prerelease=False, html_url=URL) | changes
+
+    def gh_calls(self):
+        return [call.args[0] for call in self.output.call_args_list if call.args[0][0] == "gh"]
+
+    def test_creates_release_using_exact_notes_and_existing_tag(self):
+        notes.publish_notes("0.2.0", SHA, False, BODY)
+        (command,) = self.gh_calls()
+        self.assertIn("--verify-tag", command)
+        self.assertEqual(command[command.index("--target") + 1], SHA)
+        self.assertNotIn("--prerelease", command)
+        self.assertEqual(self.created_notes, BODY)
+        self.run.assert_called_once_with(
+            ["git", "fetch", "--force", "origin", "refs/tags/v0.2.0:refs/tags/v0.2.0"],
+            check=True,
+        )
+
+    def test_marks_prerelease_without_promoting_latest(self):
+        notes.publish_notes("0.2.0-rc.1", SHA, True, BODY)
+        (command,) = self.gh_calls()
+        self.assertIn("--prerelease", command)
+        self.assertIn("--latest=false", command)
+
+    def test_matching_rerun_has_no_release_write(self):
+        self.lookup.return_value = self.release()
+        notes.publish_notes("0.2.0", SHA, False, BODY)
+        self.assertFalse(self.gh_calls())
+
+    def test_conflicts_fail_without_overwriting_release(self):
+        for change in (
+            {"body": "Different notes"},
+            {"draft": True},
+            {"prerelease": True},
+            {"tag_name": "v0.3.0"},
+            {"name": "Other"},
+        ):
+            with self.subTest(change=change):
+                self.lookup.return_value = self.release(**change)
+                with self.assertRaisesRegex(ValueError, "differs"):
+                    notes.publish_notes("0.2.0", SHA, False, BODY)
+                self.assertFalse(self.gh_calls())
+
+    def test_wrong_checkout_stops_before_tag_fetch_or_api(self):
+        self.output.return_value = "b" * 40
+        self.output.side_effect = None
+        with self.assertRaisesRegex(ValueError, "approved commit"):
+            notes.publish_notes("0.2.0", SHA, False, BODY)
+        self.run.assert_not_called()
+        self.lookup.assert_not_called()
+
+    def test_wrong_tag_commit_stops_before_api(self):
+        self.output.side_effect = [SHA, "tag", "b" * 40]
+        with self.assertRaisesRegex(ValueError, "does not point"):
+            notes.publish_notes("0.2.0", SHA, False, BODY)
+        self.lookup.assert_not_called()
+
+    def test_missing_remote_tag_stops_before_api(self):
+        self.run.side_effect = subprocess.CalledProcessError(1, ["git", "fetch"])
+        with self.assertRaises(subprocess.CalledProcessError):
+            notes.publish_notes("0.2.0", SHA, False, BODY)
+        self.lookup.assert_not_called()
+
+    def test_lightweight_tag_stops_before_api(self):
+        self.output.side_effect = [SHA, "commit"]
+        with self.assertRaisesRegex(ValueError, "annotated"):
+            notes.publish_notes("0.2.0", SHA, False, BODY)
+        self.lookup.assert_not_called()
+
+    def test_lookup_failure_does_not_create_release(self):
+        self.lookup.side_effect = urllib.error.URLError("connection failed")
+        with self.assertRaises(urllib.error.URLError):
+            notes.publish_notes("0.2.0", SHA, False, BODY)
+        self.assertFalse(self.gh_calls())
+
+
+class LookupTests(unittest.TestCase):
+    @patch.dict(os.environ, {"GH_TOKEN": "test-token"})
+    @patch.object(notes.urllib.request, "urlopen")
+    def test_only_404_means_release_missing(self, urlopen):
+        for status in (404, 401, 403, 500):
+            with self.subTest(status=status):
+                urlopen.side_effect = urllib.error.HTTPError(
+                    "https://api.github.com", status, "error", {}, io.BytesIO()
+                )
+                if status == 404:
+                    self.assertIsNone(notes.existing_release("example/sdk", "v0.2.0"))
+                else:
+                    with self.assertRaises(urllib.error.HTTPError):
+                        notes.existing_release("example/sdk", "v0.2.0")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index eaf8999..acac6ee 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -34,3 +34,13 @@ jobs:
           python-version: '3.12'
       - run: uv sync --extra dev --locked
       - run: uv run make docs-check
+
+  release-notes:
+    name: release-notes
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - name: Validate changelog
+        run: python3 .github/scripts/release_notes.py check
+      - name: Test release notes automation
+        run: python3 -m unittest discover -s .github/scripts -p 'test_*.py'
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index f024190..3fae18e 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -37,6 +37,7 @@ jobs:
       RELEASE_COMMIT_SHA: ${{ inputs.commit_sha }}
       RELEASE_BATCH_ID: ${{ inputs.batch_id }}
     outputs:
+      prerelease: ${{ steps.version.outputs.prerelease }}
       artifact_name: ${{ steps.artifact.outputs.artifact_name }}
       wheel_name: ${{ steps.artifact.outputs.wheel_name }}
       wheel_sha256: ${{ steps.artifact.outputs.wheel_sha256 }}
@@ -103,7 +104,8 @@ jobs:
       - name: Install locked release dependencies
         run: uv sync --extra dev --extra release --locked
 
-      - name: Validate release version and commit
+      - id: version
+        name: Validate release version and commit
         run: |
           set -euo pipefail
           git fetch --force --prune --prune-tags origin \
@@ -134,6 +136,8 @@ jobs:
               raise SystemExit(f"invalid PEP 440 version: {raw}: {exc}") from exc
           if parsed.local is not None or str(parsed) != raw:
               raise SystemExit(f"version must be canonical public PEP 440: {raw} (canonical: {parsed})")
+          with open(os.environ["GITHUB_OUTPUT"], "a") as output:
+              print(f"prerelease={str(parsed.is_prerelease).lower()}", file=output)
           print(parsed)
           PY
           )
@@ -150,6 +154,16 @@ jobs:
           fi
           echo "SOURCE_DATE_EPOCH=$(git show -s --format=%ct "$RELEASE_COMMIT_SHA")" >> "$GITHUB_ENV"
 
+      - name: Validate and preview release notes
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+        run: |
+          set -euo pipefail
+          python3 .github/scripts/release_notes.py extract \
+            --version "$RELEASE_VERSION" --output "$RUNNER_TEMP/release-notes.md"
+          echo "## Changelog for v$RELEASE_VERSION" >> "$GITHUB_STEP_SUMMARY"
+          cat "$RUNNER_TEMP/release-notes.md" >> "$GITHUB_STEP_SUMMARY"
+
       - id: state
         name: Inspect tag and PyPI state
         run: |
@@ -494,3 +508,28 @@ jobs:
           assert all((Forward, Managed, AsyncForward, AsyncManaged))
           PY
           echo "Verified clean installation and public imports for $PACKAGE_NAME==$RELEASE_VERSION." >> "$GITHUB_STEP_SUMMARY"
+
+  github-release:
+    name: publish release notes
+    needs: [preflight, verify]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      GH_TOKEN: ${{ github.token }}
+      RELEASE_VERSION: ${{ inputs.version }}
+      RELEASE_COMMIT_SHA: ${{ inputs.commit_sha }}
+      RELEASE_PRERELEASE: ${{ needs.preflight.outputs.prerelease }}
+    steps:
+      - name: Check out the approved commit
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ inputs.commit_sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Create or verify GitHub Release
+        run: |
+          python3 .github/scripts/release_notes.py publish \
+            --version "$RELEASE_VERSION" \
+            --commit-sha "$RELEASE_COMMIT_SHA" \
+            --prerelease "$RELEASE_PRERELEASE"
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..4223f3a
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,13 @@
+# Changelog
+
+User-facing changes to this SDK are recorded here. History starts at the
+existing `0.1.0` release; earlier development prereleases are not listed.
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- Forward and Managed: synchronous and asynchronous clients with typed requests and responses.
+- Support pagination, SSE streaming, and file transfer on Python 3.10 and newer.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2b6c694..81e952e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -50,11 +50,56 @@ Contract fixtures are maintained manually. A passing fixture test proves consist
 
 The SDK intentionally keeps Qoder-branded `X-Qoder-*` metadata headers, resumable session-event streams, and Python-native synchronous and asynchronous clients. Preserve those extensions unless the change explicitly revises the public contract. Breaking public API changes require a minor-version release while the SDK remains pre-1.0 and must include migration notes.
 
+## Changelog
+
+Keep user-facing notes in [CHANGELOG.md](CHANGELOG.md). Add a concise bullet under
+`## [Unreleased]` in the same PR as a feature, fix, deprecation, or behavior change.
+Use English consistently with the public documentation, identify Forward or Managed
+when relevant, and describe the effect on SDK users. Pure CI changes and internal
+refactors normally need no entry; explain that in the PR checklist.
+
+Use `### Added`, `### Fixed`, `### Changed`, `### Breaking changes`, and
+`### Migration` as needed. Omit empty categories. Breaking changes must explain
+what callers need to change, preferably with a small migration example. Use inline
+links for issues and PRs so the extracted entry also works on the Releases page.
+
+In the release PR, move the completed `Unreleased` notes into exactly one
+`## [<version>]` section immediately below it, alongside the version-file updates.
+Keep an empty `Unreleased` section for subsequent work. A date is optional; when
+included, use `## [<version>] - YYYY-MM-DD`. Use the exact canonical package version
+without `v`, including any prerelease suffix. Each SDK keeps its own version and
+notes; a shared `batch_id` can associate coordinated releases.
+
+Validate the file and preview a prepared version locally (Python 3.10+):
+
+```bash
+python3 .github/scripts/release_notes.py check
+python3 .github/scripts/release_notes.py extract --version <version>
+python3 -m unittest discover -s .github/scripts -p 'test_*.py'
+```
+
+PR CI checks the format and release automation tests. Release preflight requires a
+nonempty entry for the requested version, rejects placeholders such as `TODO` or
+`TBD`, and displays the extracted notes in the workflow summary before approval.
+Only approved-commit notes are used; the workflow never writes back to `main`.
+
+After public package verification succeeds, the workflow creates a GitHub Release
+on the existing annotated `v<version>` tag using that entry. Prereleases are marked
+as such and are not promoted to Latest. A rerun checks the remote tag's commit and
+reuses a published Release only when its title, notes, and prerelease flag match.
+Conflicting or draft Releases fail for manual inspection rather than being
+silently overwritten. If only this final step fails, rerun the failed job to finish
+the Release; the package may already be publicly available.
+
+The `0.1.0` entry documents the existing baseline. This automation applies to future
+release commits that contain the changelog and scripts; it does not move old tags
+or republish historical packages.
+
 ## Release
 
 Before the first release, create the GitHub `release` Environment with required reviewers and a deployment-branch rule limited to `main`. Add a tag ruleset for `refs/tags/v*` that blocks updates and deletions and allows creation only by the release automation identity. Update the PyPI Trusted Publisher for `QoderAI/qoder-cloud-agents-sdk-python` and `release.yml` to require the same `release` Environment. Do not dispatch the workflow until all settings are active.
 
-1. Merge a release pull request that updates `project.version` in `pyproject.toml`, refreshes `uv.lock`, and passes all normal checks.
+1. Merge a release pull request that updates `project.version` in `pyproject.toml`, refreshes `uv.lock`, prepares the matching version entry in `CHANGELOG.md`, and passes all normal checks.
 2. From the resulting `origin/main`, record the full lowercase 40-character commit SHA and dispatch the workflow from `main`. Use a 1-64 character `batch_id` that starts with a letter or digit and otherwise contains only letters, digits, `.`, `_`, or `-`:
 
    ```bash
@@ -64,7 +109,7 @@ Before the first release, create the GitHub `release` Environment with required
      -f batch_id=<safe-audit-token>
    ```
 
-3. After approval, the workflow creates or reuses the annotated `v<version>` tag, publishes the approved wheel and sdist with PyPI Trusted Publishing, verifies their public digests, and performs a no-cache installation of the exact version and its synchronous and asynchronous imports.
+3. After approval, the workflow creates or reuses the annotated `v<version>` tag, publishes the approved wheel and sdist with PyPI Trusted Publishing, verifies their public digests, and performs a no-cache installation of the exact version and its synchronous and asynchronous imports. After verification, it publishes the changelog entry as a GitHub Release.
 
 PyPI versions are immutable. Never reuse or overwrite one: fix forward with a new release pull request and version, and yank an unusable version when necessary. A safe rerun must use the same SHA, version, and `batch_id`; it verifies the existing PyPI files without uploading them again.
 
diff --git a/README.md b/README.md
index 2b31e25..425eca5 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
 # Qoder Cloud Agents Python SDK
 
+[Changelog](CHANGELOG.md) · [Releases](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/releases)
+
 [![PyPI version](https://img.shields.io/pypi/v/qca-sdk.svg)](https://pypi.org/project/qca-sdk/)
 
 The Qoder Cloud Agents Python SDK provides access to the Qoder Cloud Agents API from Python 3.10+. It ships synchronous and natively asynchronous clients, typed request parameters and response models, automatic pagination, SSE streaming, and file transfer.

From 6206f651876d4d33d86f61a5718700c3722b98b3 Mon Sep 17 00:00:00 2001
From: moonyue-w <300878504+moonyue-w@users.noreply.github.com>
Date: Thu, 24 Sep 2026 10:46:29 +0800
Subject: [PATCH 2/2] fix(client): align timeout defaults with Anthropic

---
 CHANGELOG.md                   |  4 ++++
 README.md                      |  2 +-
 src/qca/common/_base_client.py |  2 +-
 tests/test_client.py           |  2 +-
 tests/test_public_contract.py  | 38 ++++++++++++++++++++++++++++++++++
 5 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4223f3a..7f7cd01 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,10 @@ existing `0.1.0` release; earlier development prereleases are not listed.
 
 ## [Unreleased]
 
+### Changed
+
+- Forward and Managed clients, both synchronous and asynchronous, now default to a 5-second connection timeout and 600-second read, write, and connection-pool timeouts, matching Anthropic's Python SDK. SSE streams can continue beyond 10 minutes while data keeps arriving within the read timeout.
+
 ## [0.1.0]
 
 ### Added
diff --git a/README.md b/README.md
index 425eca5..d9ef2d2 100644
--- a/README.md
+++ b/README.md
@@ -254,7 +254,7 @@ client.with_options(max_retries=5).sessions.list()  # or override per call site
 
 ## Timeouts
 
-The default timeout is 10 seconds to connect and 60 seconds for each subsequent phase. Pass a float of seconds, an `httpx.Timeout`, or `None` to disable.
+The default timeout is 5 seconds to connect and 600 seconds each for reading data, writing data, and acquiring a connection from the pool, matching Anthropic's Python SDK. These are phase timeouts, not a total request deadline. Pass a float of seconds, an `httpx.Timeout`, or `None` to disable.
 
 ```python
 client = Forward(timeout=30.0)
diff --git a/src/qca/common/_base_client.py b/src/qca/common/_base_client.py
index 9a95555..c8c7a7e 100644
--- a/src/qca/common/_base_client.py
+++ b/src/qca/common/_base_client.py
@@ -31,7 +31,7 @@
 from .credentials import AsyncCredential, Credential
 from .pagination import AsyncPage, SyncPage
 
-DEFAULT_TIMEOUT = httpx.Timeout(60.0, connect=10.0)
+DEFAULT_TIMEOUT = httpx.Timeout(600.0, connect=5.0)
 
 
 def _timeout_seconds(timeout: Any) -> int | None:
diff --git a/tests/test_client.py b/tests/test_client.py
index a530939..6630ae9 100644
--- a/tests/test_client.py
+++ b/tests/test_client.py
@@ -139,7 +139,7 @@ def test_client_fingerprint_reports_language_version_platform_and_deadline():
     assert headers["x-qoder-os"] in {"MacOS", "Windows", "Linux", "iOS", "Android", "FreeBSD", "OpenBSD"}
     assert headers["x-qoder-arch"] in {"x32", "x64", "arm", "arm64"}
     assert headers["x-qoder-retry-count"] == "0"
-    assert headers["x-qoder-timeout"] == "60"
+    assert headers["x-qoder-timeout"] == "600"
     assert requests[1].headers["x-qoder-timeout"] == "7"
 
 
diff --git a/tests/test_public_contract.py b/tests/test_public_contract.py
index c7f1f4b..dd5a8da 100644
--- a/tests/test_public_contract.py
+++ b/tests/test_public_contract.py
@@ -54,6 +54,44 @@
 ]
 
 
+@pytest.mark.parametrize("client_cls", SYNC_CLIENTS)
+def test_default_and_explicit_timeouts_reach_sync_transport(client_cls):
+    requests = []
+    http = httpx.Client(
+        transport=httpx.MockTransport(lambda r: requests.append(r) or httpx.Response(200, json={"data": []}))
+    )
+    with client_cls(pat="test-token", http_client=http) as client:
+        client.models.list()
+        client.with_options(timeout=30).models.list()
+        client.models.list(timeout=httpx.Timeout(20, connect=2, write=3, pool=4))
+        client.models.list(timeout=None)
+    assert [r.extensions["timeout"] for r in requests] == [
+        {"connect": 5.0, "read": 600.0, "write": 600.0, "pool": 600.0},
+        {"connect": 30, "read": 30, "write": 30, "pool": 30},
+        {"connect": 2, "read": 20, "write": 3, "pool": 4},
+        {"connect": None, "read": None, "write": None, "pool": None},
+    ]
+
+
+@pytest.mark.parametrize("client_cls", ASYNC_CLIENTS)
+async def test_default_and_explicit_timeouts_reach_async_transport(client_cls):
+    requests = []
+    http = httpx.AsyncClient(
+        transport=httpx.MockTransport(lambda r: requests.append(r) or httpx.Response(200, json={"data": []}))
+    )
+    async with client_cls(pat="test-token", http_client=http) as client:
+        await client.models.list()
+        await client.with_options(timeout=30).models.list()
+        await client.models.list(timeout=httpx.Timeout(20, connect=2, write=3, pool=4))
+        await client.models.list(timeout=None)
+    assert [r.extensions["timeout"] for r in requests] == [
+        {"connect": 5.0, "read": 600.0, "write": 600.0, "pool": 600.0},
+        {"connect": 30, "read": 30, "write": 30, "pool": 30},
+        {"connect": 2, "read": 20, "write": 3, "pool": 4},
+        {"connect": None, "read": None, "write": None, "pool": None},
+    ]
+
+
 def test_top_level_clients_sentinel_version_and_exceptions_are_public():
     # (1) The four clients, the missing-argument sentinel and its type, the
     # version and the shared public exceptions are importable from qca.