notion-api-changelog-pr

name

notion-api-changelog-pr

description

Check the Notion API changelog and upgrade guides for the notion-py repository, decide whether bounded library updates are needed, implement patches against the latest official Notion API spec, run repo validation, and prepare a draft PR when the scope is clean and GitHub auth is valid. Use when asked to review Notion API updates, compare notion-py against the latest Notion API, align notion-py with current Notion API behavior, patch breaking or thin additive gaps, or open a PR for required notion-py updates. 「Notion API の changelog を確認して notion-py の更新要否を見たい」「Notion API 更新に合わせて notion-py の差分を埋めて PR を作りたい」ときに使う。

Notion API Changelog PR

Overview

Use this skill only for /Users/higa4/dev/notion-py or an equivalent checkout of the same repository.

Track the latest official Notion API changes, classify the impact on notion-py, implement only bounded fixes against the current official spec, validate the repo, and publish a draft PR only when the scope and GitHub state are safe.

Workflow

1. Confirm the target repo

• Work only when the current repo is notion-py.
• Stop if the checkout is a different project or if the worktree contains unrelated changes.
• Before any publish step, run git status --short, git branch --show-current, git remote -v, and gh auth status.

2. Read official upstream sources only

• Start with the Notion changelog and the relevant upgrade guide for the latest breaking version.
• Read linked API docs only for the specific capability being patched.
• If SDK behavior matters, use the official JS/TS SDK release notes or source as the compatibility reference.
• Do not use blog posts, community posts, or secondary summaries as the source of truth.
• Treat the latest official Notion API spec as the correct behavior target for the PR.
• Do not preserve old request or response shapes unless the user explicitly asks for backward compatibility.

Current high-signal upstream baseline:

• 2026-03-11 is a breaking API version.
• The upgrade guide says to replace after with position, archived with in_trash, and transcription with meeting_notes.
• The upgrade guide says @notionhq/client v5.12.0 or later supports opt-in use of 2026-03-11.

3. Scan the repo before deciding what to patch

• Read references/change-rubric.md to keep the classification consistent.
• Run python3 scripts/repo_gap_scan.py --repo-root .. --format markdown.
• Use references/repo-map.md to jump straight to likely edit points.
• Treat the scanner output as the initial worklist, then confirm each candidate in code before editing.

4. Classify every upstream change

Classify each item into exactly one bucket:

• auto-fix: bounded work that fits existing repo patterns and aligns the library to the current official Notion API.
• report-only: too large or too open-ended for a safe automatic patch.
• no-op: already supported or not relevant to the repo.

Bounded auto-fix scope:

• update the client to the latest breaking API version and make that version the repo's source of truth
• replace after with position
• replace request-side or response-side archived handling with in_trash
• replace transcription with meeting_notes
• add small enum, literal, union, request, response, or thin endpoint-facade support
• update docs and unit tests that directly cover the changed surface

Report-only scope:

• large new API groups such as Views when the repo has no existing equivalent façade
• schema-heavy additions that would require broad modeling beyond a bounded patch
• release management, package version bumps, or semver decisions

Never bump the package version automatically as part of this workflow.

5. Patch only bounded fixes

• Follow existing repo conventions before introducing any new abstraction.
• Prefer the same public shape the repo already uses: TypedDict for API parameter dictionaries, Pydantic models for structured requests and responses, thin API façade methods in notion_client.py, and corresponding docs under docs/.
• Implement against the latest official spec first, not against backward compatibility shims.
• Prefer replacing legacy fields and behavior over supporting both old and new paths in parallel.
• Update only the minimal set of docs and tests needed to keep examples and current-spec behavior honest.

6. Validate before publish

Run the smallest meaningful set of checks first, then widen only if needed:

• uv run pytest test/unit -v
• a focused dry run of the scanner: python3 scripts/repo_gap_scan.py --repo-root .. --format markdown

Expect the scanner to flag these kinds of items when still missing:

• 2026-03-11 compatibility changes as auto-fix
• views support as report-only

7. Publish only when the repo is safe

Do not publish when any of these are false:

• the worktree scope is clean
• the intended patch has passing validation
• gh auth status succeeds
• the remote is GitHub

When publish is allowed:

• delegate branch, commit, push, and draft PR creation to the GitHub yeet skill
• keep the PR as draft by default
• summarize auto-fix, report-only, and any deferred follow-up in the PR body

When publish is blocked:

• stop cleanly
• report the exact blocker
• if gh auth status is invalid, instruct the user to re-authenticate before retrying PR creation

Resources

scripts/repo_gap_scan.py

Scan notion-py for the highest-signal Notion API compatibility anchors and classify each one as auto-fix, report-only, or no-op.

Use it to detect:

• 2026-03-11 version support
• after vs position
• archived vs in_trash
• transcription vs meeting_notes
• heading_4
• tab
• custom_emojis
• Views API support
• markdown endpoint support
• writable verification support
• native icon request/response support

references/change-rubric.md

Read this first when deciding whether a changelog item stays inside bounded scope.

references/repo-map.md

Use this as the fast path to the files most likely to require edits.

Output expectations

• Start with a short impact summary grounded in the official changelog.
• List the worklist grouped by auto-fix, report-only, and no-op.
• If patches were made, report the validation commands you ran and whether they passed.
• If a PR was not created, explain why in one sentence and stop instead of improvising around the blocker.