homebrew-formula-maintenance

Homebrew Formula のメンテナンス

概要

このワークフローを使用して、Python CLI の Homebrew formula を PyPI のリリースと同期させます。tap での基本的な流れは、バージョンと SHA を更新し、必要に応じてリソースブロックを更新し、brew install／test／audit を実行してから、tap の更新をプッシュすることです（手動または CI 経由）。

クイックスタート（手動での更新）

1. PyPI にリリースが存在することを確認し、sdist の URL と SHA256 を取得します。
2. formula の url と sha256 を更新します。
3. formula が virtualenv_install_with_resources を使用している場合は、resource スタンザを更新します。
4. テストを実行します：brew install --build-from-source ＋ brew test ＋ brew audit --strict。
5. 変更履歴／タグを更新し、tap リポジトリにプッシュします。

すでに使用しているローカルスクリプト

• homebrew-claude-mpm/scripts/update_formula.sh <version>
  • PyPI を確認し、url／sha を更新してリソースを再生成します。brew test／audit は任意で実行できます。
• homebrew-claude-mpm/scripts/generate_resources.py
  • PyPI から Python 依存関係の resource ブロックを生成します。
• homebrew-claude-mpm/scripts/test_formula.sh
  • brew install／test／audit／style をエンドツーエンドで実行します。
• mcp-vector-search/scripts/update_homebrew_formula.py
  • --dry-run、--version、--tap-repo-path、HOMEBREW_TAP_TOKEN を使用した、エンドツーエンドの tap 更新です。

標準的なワークフロー

1. PyPI リリースを確認する

• sdist が利用可能であることを確認し、URL／SHA を記録します。
• 一般的なコマンド：curl -s https://pypi.org/pypi/<package>/<version>/json

2. Formula の URL と SHA を更新する

• Formula/<name>.rb の url と sha256 を置き換えます。
• sdist URL によって formula のバージョンが暗黙的に決まる状態を維持します（各 tap ではこの方式を採用しています）。

3. リソースを更新する（Python 仮想環境の formula）

formula が Language::Python::Virtualenv と virtualenv_install_with_resources を使用している場合：

• 依存関係が変更されたら、resource スタンザを再生成します。
• generate_resources.py などを使用し、貼り付ける前に出力を確認します。

4. テストと監査を行う

tap リポジトリで次を実行します：

brew install --build-from-source ./Formula/<name>.rb
brew test <name>
brew audit --strict ./Formula/<name>.rb
brew style ./Formula/<name>.rb

5. コミットしてプッシュする

• tap リポジトリでリリースを追跡している場合は、CHANGELOG.md を更新します。
• tap のワークフローに従って、コミット、タグ付け、プッシュを行います。

Formula のパターン（各 tap の例）

完全な仮想環境 formula（claude-mpm）

• Language::Python::Virtualenv をインクルード
• virtualenv_install_with_resources
• 依存関係を固定する大規模な resource ブロック
• test do では、--version やサブコマンドなどの CLI コマンドを使用

最小構成の venv formula（mcp-vector-search）

• venv を明示的に作成し、pip install -v buildpath を実行
• CLI エントリーポイントに bin.install_symlink を使用
• test do は --version と --help を使用した最小構成

CI 自動化のパターン

Homebrew の更新に使用する GitHub Actions ワークフローは、次の流れに従います：

• タグ、または CI 成功後の workflow_run をトリガーにします。
• scripts/update_homebrew_formula.py を実行します。
• HOMEBREW_TAP_TOKEN を必須とし、HOMEBREW_TAP_REPO は任意で指定します。
• 失敗した場合は、手動で更新する手順を記載した issue を作成します。

トラブルシューティング

• PyPI にリリースがない：タグのプッシュと公開手順が完了していることを確認します。
• SHA が一致しない：PyPI JSON から sdist の SHA を再取得します。
• brew audit の失敗：依存関係の resource ブロックが sdist と一致していること、および [email protected] 依存関係が存在することを確認します。
• インストールの失敗：[email protected] 依存関係と virtualenv_install_with_resources の使用方法を確認します。

関連スキル

• toolchains/universal/infrastructure/github-actions
• toolchains/universal/infrastructure/docker