homebrew-formula-maintenance

Homebrew Formula Maintenance Overview

Use this workflow to keep Homebrew formulas in sync with PyPI releases for Python CLIs. The pattern in your taps is: update version + sha, refresh resource blocks when needed, run brew install/test/audit, then push the tap update (manually or via CI).

Quick Start (manual bump) Verify the PyPI release exists and grab the sdist URL + SHA256. Update the url and sha256 in the formula. Refresh resource stanzas if the formula uses virtualenv_install_with_resources. Test: brew install --build-from-source + brew test + brew audit --strict. Update changelog/tag and push the tap repo. Local Scripts You Already Use homebrew-claude-mpm/scripts/update_formula.sh Verifies PyPI, updates url/sha, regenerates resources, optional brew test/audit. homebrew-claude-mpm/scripts/generate_resources.py Emits Python dependency resource blocks from PyPI. homebrew-claude-mpm/scripts/test_formula.sh End-to-end brew install/test/audit/style. mcp-vector-search/scripts/update_homebrew_formula.py End-to-end tap update with --dry-run, --version, --tap-repo-path and HOMEBREW_TAP_TOKEN. Standard Workflow 1. Confirm PyPI Release Check the sdist is available and capture URL/SHA. Typical command: curl -s https://pypi.org/pypi///json. 2. Update Formula URL + SHA Replace url and sha256 in Formula/.rb. Keep the formula version implicit via the sdist URL (your taps do this). 3. Refresh Resources (Python Virtualenv Formula)

If the formula uses Language::Python::Virtualenv and virtualenv_install_with_resources:

Regenerate resource stanzas after dependency changes. Use generate_resources.py or equivalent; review output before pasting. 4. Test and Audit

Run these in the tap repo:

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

1. Commit and Push Update CHANGELOG.md if the tap repo tracks releases. Commit, tag, and push as required by the tap workflow. Formula Patterns (From Your Taps) Full Virtualenv Formula (claude-mpm) include Language::Python::Virtualenv virtualenv_install_with_resources Large resource blocks to pin dependencies test do uses CLI commands like --version and subcommands Minimal Venv Formula (mcp-vector-search) Create venv explicitly and pip install -v buildpath bin.install_symlink for CLI entrypoint Minimal test do uses --version and --help CI Automation Pattern

Your GitHub Actions workflow for Homebrew updates follows this flow:

Trigger on tag or workflow_run after CI succeeds. Run scripts/update_homebrew_formula.py. Require HOMEBREW_TAP_TOKEN (and optional HOMEBREW_TAP_REPO). On failure, open an issue with manual update steps. Troubleshooting PyPI release missing: verify tag push and publish step completed. SHA mismatch: re-fetch sdist SHA from PyPI JSON. brew audit failures: confirm dependency resource blocks match the sdist and python@x.y dependency is present. Install failures: verify python@x.y dependency and virtualenv_install_with_resources usage. Related Skills toolchains/universal/infrastructure/github-actions toolchains/universal/infrastructure/docker