hs-release

Hindsight リリース

コア Hindsight リリースを作成し、付随する変更履歴／ブログ PR を開きます。これはコア製品バージョン（API、クライアント、CLI、コントロールプレーン、Helm）向けです。インテグレーションは個別にバージョン管理されます — それらにはこのスキルではなく scripts/release-integration.sh を使用してください。

リリースは不可逆であり、外部向けです。バージョンにタグを付け、それを直接 main にプッシュし、それによって PyPI / npm / Helm にパッケージを公開する CI がトリガーされます。開始する前に、バージョン番号と、意図した修正がすでに main にマージされていることを確認してください。

ステップ 0 — 事前確認

1. ベースを決めます。 リリースは最新の origin/main から作成し、フィーチャーブランチからは決して作成しません。まず git fetch origin --tags を実行します。ユーザーが意図する「いくつかの修正」が実際に main にマージされていることを確認します（git log v<prev>..origin/main --oneline）。
2. main がどこにチェックアウトされているかを確認します。 main は多くの場合、すでに兄弟ワークツリーにチェックアウトされています（git worktree list）。2 つ目のワークツリーで main をチェックアウトすることはできません — すでにそれを保持しているワークツリーでリリースを実行してください。そのワークツリーが使い捨ての不要物（.next-* の tsconfig パス、スクリーンショット）で汚れている場合は、git stash push -u を実行し、origin/main にファストフォワードして、リリースを実行し、その後 git stash pop を実行します。
3. 落とし穴: git checkout main 2>&1 | tail && git reset --hard ... のような && チェーンでチェックアウトをパイプしないでください — パイプの終了ステータスは tail のもの（常に 0）であるため、チェックアウトが失敗してもチェーンは停止せず、reset が誤ったブランチで実行されます。チェックアウトは独立したコマンドとして実行し、リセットする前に git branch --show-current を確認してください。

ステップ 1 — リリースを作成する

クリーンな main 上のワークツリーから実行します：

./scripts/release.sh <version>     # e.g. 0.8.1  (no leading v)

release.sh はすべてのコンポーネントのバージョンを更新し、OpenAPI スペックとすべてのクライアント SDK を再生成し、ドキュメントのバージョニングを更新し、Release v<version> をコミットし、v<version> にタグを付け、コミットとタグを直接 main にプッシュします。このプッシュが、パッケージをビルドして公開する Release GitHub Actions ワークフローをトリガーします。これは**** PR ではありません。

実行後に確認します：gh run list --limit 5 に Release v<version> ワークフローが実行中と表示され、git ls-remote --tags origin v<version> がタグを返すはずです。

ステップ 2 — 変更履歴 + ブログ PR（別途）

タグが存在した後に、独自の PR として行います（前例：v0.8.0 = #2053、v0.8.1 = #2080）。新しい main から分岐したブランチで作業します：

git checkout -b docs-changelog-<version> origin/main

それ以外にクリーンなチェックアウトが得られない場合にのみ、別のワークツリーを立ち上げてください（git worktree add ../hindsight-changelog-<version> -b docs-changelog-<version> origin/main）— たとえば、main が別のワークツリーに保持されていて、現在のワークツリーに邪魔したくない作業がある場合などです。

ブランチ命名： docs-（ハイフン）の慣例を使用します（例：docs-changelog-0.8.1）。docs という名前のリモートブランチが文字通り存在するため、docs/... というブランチはプッシュ時に directory file conflict で拒否されます。

変更履歴

uv run --directory hindsight-dev generate-changelog <version>

前回のタグと v<version> の間のコミットを LLM が要約し、hindsight-docs/src/pages/changelog/index.md の先頭にエントリを追加します。

エントリは、範囲内で追加されたすべての Alembic マイグレーションを列挙する Database Migrations セクションで終わり、それぞれがそれを導入した PR にリンクします。このセクションは git から決定的に列挙され（hindsight_api/alembic/versions/ に対する --diff-filter=A）、LLM によるものではありません — 手で編集しないでください。また、マイグレーションが欠けている場合は、そのコミットがタグ範囲内で実際にファイルを追加したか確認してください。OPENAI_API_KEY が必要です（すでにリポジトリの .env にあります）。これは hindsight-integrations/ のソースを除外しますが、コミットがドキュメントにも触れた新しいインテグレーションは依然として表示されます — それは前例と一致するので、変更履歴に残してください。

ブログ記事

hindsight-docs/blog/YYYY-MM-DD-version-X-Y-Z.md を手書きします（既存のものを参考にしてください。パッチリリースは短いです — 2026-06-02-version-0-7-2.md を参照）。ガイドライン:

• 内部構造や仕組みではなく、ユーザーへの影響を説明します。 ユーザーが何をできるようになったか、何を設定すべきかを最初に書きます。設定項目や環境変数の名前は問題ありません（開発者向け）が、コードシンボルや内部構造は避けます。
• リリースブログに連携機能を列挙しないでください。 コアブログではコアエンジン / API / 運用の変更を扱い、各連携機能は独自の変更履歴を持ちます（連携機能が生成された changelog/index.md に含まれていても問題ありません。ブログには含めないでください）。
• 運用やデータ整合性の修正がある場合は、アップグレードの推奨を明記してください。
• フォーマットを検証します: npx prettier --check <blog file>。

docs スキルを同期する

./scripts/generate-docs-skill.sh

skills/hindsight-docs/references/changelog/index.md を更新します。また、skills/hindsight-docs/references/openapi.json を 1 バージョン分進めます — release.sh は OpenAPI を更新する前にスキルを再生成するため、リリースコミットではスキルのコピーが 1 バージョン遅れます。この手順でそれを同期します。version に 1 行の差分が生じますが、そのままにしてください。

コミット、プッシュ、PR

git add -A
git commit --no-verify -m "docs: changelog and blog post for v<version>"
git push -u origin docs-changelog-<version>
gh pr create --base main --title "docs: changelog and blog post for v<version>" --body "..."

PR に含まれるべきファイル: 変更履歴のエントリ、新しいブログ記事、再生成されたスキル変更履歴のミラー、そしてスキル openapi.json のバージョン同期です。

クリーンアップ

一時的なワークツリーを作成した場合は、PR を上げたら削除します（git worktree remove ../hindsight-changelog-<version>。ブランチは origin に残ります）。ステップ 0 で pop した stash があれば復元します。