notion-upgrade-migration

# Notion Upgrade & Migration ## Overview Step-by-step guide for upgrading `@notionhq/client` (Node.js) and `notion-client` (Python) SDK versions, migrating between Notion API versions, handling breaking changes, and adopting newly released features. Covers the current stable API version `2022-06-28` and the SDK feature timeline through v2.x. ## Prerequisites - Existing project with `@notionhq/client` or `notion-client` installed - Git repository with clean working tree (no uncommitted changes) - Test suite covering Notion API calls (or willingness to add verification tests) - `NOTION_TOKEN` environment variable configured ## Instructions ### Step 1: Audit Current Versions and API Surface Determine what you are running today before changing anything. ```bash # Node.js — check installed SDK version npm ls @notionhq/client # Node.js — check latest available npm view @notionhq/client version # Python — check installed SDK version pip show notion-client 2>/dev/null | grep Version # Python — check latest available pip index versions notion-client 2>/dev/null | head -1 # Find which API version your code specifies grep -rn "notionVersion\|Notion-Version\|notion_version" src/ lib/ app/ 2>/dev/null ``` Record the current SDK version and API version before proceeding. If no `notionVersion` is set explicitly, the SDK uses its built-in default (typically `2022-06-28` for current releases). **SDK version history — key milestones:** | SDK Version | Notable Additions | |------...