リリース手順¶

magic-pocket (runtime lib) と magic-pocket-cli (deploy CLI) を PyPI へ リリースするときの手順。tag X.Y.Z の push で GitHub Actions (.github/workflows/release.yml、PyPI Trusted Publishing / OIDC) が両パッケージを build & publish する。

バージョンの決め方 (SemVer)¶

• バグ修正のみ → patch (例: 0.2.1 → 0.2.2)
• 後方互換な新機能 → minor (例: 0.3.0 → 0.4.0)。0.x でも feature は minor
• 破壊的変更 → 0.x ではコミット内容次第で minor に含める (1.0 以降は major)

### Features を含むリリースは原則 minor バンプ。

手順¶

1. version をバンプする (tag と一致が必須。release.yml の "Check tag matches package versions" が両 pyproject の version == tag を検証する):
2. pyproject.toml の version
3. packages/magic-pocket-cli/pyproject.toml の version と依存 magic-pocket>=X.Y.Z,<X.(Y+1) (上限も同 minor に束縛する。0.x では minor が breaking の単位のため、上限なしだと cli を version pin した消費者にも lib の 破壊的変更がリリース当日に届いて deploy が壊れる)
4. uv.lock を反映する (version バンプで差分が出る。uv lock か uv run で更新)。
5. CHANGELOG を確定する: [Unreleased] を ## [X.Y.Z](https://github.com/worgue/magic-pocket/releases/tag/X.Y.Z) - YYYY-MM-DD に書き換える。
6. コミットする: :bookmark: X.Y.Z リリース (<要約>)。
7. dev を push する: git push origin dev (pre-push hook で gitleaks / ruff / semgrep / pyright / pytest が走る。green でないと push されない)。
8. tag を作成して push する: git tag -a X.Y.Z -m "..." → git push origin X.Y.Z。 これで release.yml が発火し PyPI publish される。
9. publish を確認する: gh run watch <id> で workflow 成功を確認し、 curl -s https://pypi.org/pypi/magic-pocket/json 等で latest が X.Y.Z になることを確認。

リリース後に必ず実行する (毎回)¶

1. example の magic-pocket バージョンを更新する (example-neon / example-tidb は PyPI 公開版 magic-pocket[django]==X.Y.Z を pin 参照している):
2. 各 example-*/pyproject.toml の magic-pocket[django]==X.Y.Z を新バージョンへ更新
3. 各 example で uv lock
4. 4 ファイル (pyproject.toml + uv.lock × 2 example) をコミット: :arrow_up: example の magic-pocket を X.Y.Z に更新

!!! note "vendor wheel は廃止済み" 以前は git 管理外の vendor wheel を参照していたが、gitignore + 非決定的ビルドで wheel を作り直すと uv.lock のハッシュが不一致になり uv sync --frozen が落ちる footgun があったため PyPI 版に切替えた。この版更新は Dependabot でも自動化できる ので、リリース直後の必須手順ではなくなった (Dependabot PR を待つ運用でもよい)。 未リリース変更を example で検証したいときだけ、一時的に [tool.uv.sources] で ローカル wheel を override する。

1. GitHub Release オブジェクトを作成する (毎回。CHANGELOG の当該節を本文にする):

gh release create X.Y.Z --title "X.Y.Z" --notes "<CHANGELOG の該当節>"