homebrew-formula-maintenance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Homebrew Formula Maintenance

Homebrew Formula维护

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).

使用此工作流可让Homebrew formula与Python CLI的PyPI发布保持同步。你的tap中的操作模式为：更新版本+SHA，必要时刷新资源块，运行brew install/test/audit，然后推送tap更新（手动或通过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.

确认PyPI版本已发布，获取sdist URL及SHA256值。
更新formula中的
```
url
```
和
```
sha256
```
字段。

若formula使用

virtualenv_install_with_resources

，则刷新

resource

代码块。

测试：执行

brew install --build-from-source

brew test

brew audit --strict

。

更新变更日志/标签并推送tap仓库。

Local Scripts You Already Use

你已在使用的本地脚本

```
homebrew-claude-mpm/scripts/update_formula.sh <version>
```
- 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

```
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更新脚本。

Standard Workflow

标准工作流

1. Confirm PyPI Release

1. 确认PyPI版本发布

Check the sdist is available and capture URL/SHA.

Typical command:

curl -s https://pypi.org/pypi/<package>/<version>/json

检查sdist是否可用并获取URL/SHA值。

常用命令：

curl -s https://pypi.org/pypi/<package>/<version>/json

。

2. Update Formula URL + SHA

2. 更新Formula的URL + SHA

Replace
```
url
```
and
```
sha256
```
in
```
Formula/<name>.rb
```
.
Keep the formula version implicit via the sdist URL (your taps do this).

替换
```
Formula/<name>.rb
```
中的
```
url
```
和
```
sha256
```
字段。
通过sdist URL隐式指定formula版本（你的tap已采用此方式）。

3. Refresh Resources (Python Virtualenv Formula)

3. 刷新资源（Python虚拟环境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.

若formula使用

Language::Python::Virtualenv

和

virtualenv_install_with_resources

：

依赖变更后重新生成
```
resource
```
代码块。
使用
```
generate_resources.py
```
或等效工具，粘贴前需检查输出内容。

4. Test and Audit

4. 测试与审计

Run these in the tap repo:

bash

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

在tap仓库中执行以下命令：

bash

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

5. Commit and Push

5. 提交并推送

Update
```
CHANGELOG.md
```
if the tap repo tracks releases.
Commit, tag, and push as required by the tap workflow.

若tap仓库跟踪版本，更新
```
CHANGELOG.md
```
。
按照tap工作流要求提交、打标签并推送。

Formula Patterns (From Your Taps)

Formula模式（来自你的Tap）

Full Virtualenv Formula (claude-mpm)

完整虚拟环境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

```
include Language::Python::Virtualenv
```
```
virtualenv_install_with_resources
```
用于固定依赖的大型
```
resource
```
代码块
```
test do
```
部分使用
```
--version
```
等CLI命令及子命令

Minimal Venv Formula (mcp-vector-search)

极简虚拟环境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
```

显式创建虚拟环境并执行
```
pip install -v buildpath
```
使用
```
bin.install_symlink
```
配置CLI入口
```
test do
```
部分仅使用
```
--version
```
和
```
--help
```
命令

CI Automation Pattern

CI自动化模式

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.

你的Homebrew更新GitHub Actions工作流遵循以下流程：

由标签触发或在CI成功后通过
```
workflow_run
```
触发。
执行
```
scripts/update_homebrew_formula.py
```
脚本。
需要
```
HOMEBREW_TAP_TOKEN
```
（可选
```
HOMEBREW_TAP_REPO
```
）。
若执行失败，创建包含手动更新步骤的Issue。

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.

PyPI版本缺失：确认标签推送及发布步骤已完成。
SHA不匹配：重新从PyPI JSON获取sdist的SHA值。
brew audit失败：确认依赖资源块与sdist一致，且已添加
```
python@x.y
```
依赖。
安装失败：验证
```
python@x.y
```
依赖及
```
virtualenv_install_with_resources
```
的使用是否正确。