本指南把一个现有仓库中的可重复失败,缩减成便于提交 issue、调试或加入 回归测试的较小复现目录。如果只想确认 ReproMin 能运行,请先执行 README 中的 30 秒 demo。
ReproMin 需要 Python 3.9 或更高版本。下面的命令适用于 macOS 或 Linux 的 Bash/Zsh;Windows 用户可参考 PowerShell 演练中的安装、 变量和引号写法。
适合作为首次尝试的失败通常满足以下条件:
- 一条本地命令可以稳定触发目标失败;
- 原仓库太大,不适合提交 issue 或长期保留为回归样例;
- 命令不依赖凭据、私有服务、生产数据或特殊硬件;
- 你信任仓库以及它会执行的全部命令。
ReproMin 只会保留仍被失败契约接受的修改,不会诊断根因。失败契约过宽时, 结果可能很小,却不是你真正需要的复现。
下面以 Python 测试为例。先按项目原有方式选择已有的环境,在创建 ReproMin 环境前,记住那个已经安装项目测试依赖的解释器:
project_python="$(python -c 'import sys; print(sys.executable)')"
"$project_python" -m pytest --version如果找不到 pytest,先选择或准备项目自己的环境。安装 ReproMin 不会安装项目依赖。
在源仓库外创建独立环境,从经过发布检查的 GitHub Release 安装固定的 pre-alpha 开发版本。
后续通过工具的绝对路径调用,保持项目当前的环境和 PATH。
工具环境使用仍在维护的 Python 3.11+(下文的 python3),项目可以继续使用
自己的解释器。新环境在运行 pip install 前需要 pip 26.2.2 或更新版本;
如果自带的 pip 版本较旧,请按
Python 官方安全公告更新。
如果当前项目环境让 python3 指向旧版本,请把下文的 python3 替换为
工具所用维护中解释器的绝对路径。
repomin_env="$HOME/.venvs/repomin"
python3 -m venv "$repomin_env"
REPOMIN_VERSION=0.1.0.dev15
"$repomin_env/bin/python" -m pip install \
"https://github.com/fly1d/repomin/releases/download/v${REPOMIN_VERSION}/repomin-${REPOMIN_VERSION}-py3-none-any.whl"
repomin_cli="$repomin_env/bin/repomin"
"$repomin_cli" --version最后一条命令应输出 repomin 0.1.0.dev15。对应的
发布页提供 wheel、
源码归档和 SHA-256 校验值。ReproMin 目前尚未发布到 PyPI。
其他指南用 repomin 表示工具命令。按这里单独安装后,请用 "$repomin_cli"
替换它,并在同一终端中保持项目环境。
先在仓库根目录直接运行真实复现命令,确认它触发目标失败:
cd /absolute/path/to/your/repository
"$project_python" -m pytest -q tests/test_checkout.py记录能唯一识别目标失败的消息和准确退出码。本指南使用以下示例:
command: /absolute/path/to/project/.venv/bin/python -m pytest -q tests/test_checkout.py
match: AssertionError: checkout total mismatch
exit code: 1
不要只匹配 FAILED、error 或测试文件名,否则安装错误或其他断言也可能被
误认为目标失败。如果输出文本不稳定,可以改用 Java/Python 异常身份或精确的
进程失败签名;选择前请阅读 Doctor 指南。
使用 --match-text 'FAIL [checkout]: total (12)',可以直接复制有辨识度的失败消息,
不必转义正则字符。对应的正则写法是
--match 'FAIL \[checkout\]: total \(12\)'。缩减时只选一种;如果之后使用
Doctor,也沿用同一个选项和内容。v0.1.0.dev14 同时支持这两个选项;下文使用 --match。
Bash/Zsh 与 PowerShell 的引号差异见
Doctor 字面匹配说明。
设置真实源目录和一个尚不存在的同级输出目录,直接执行缩减。ReproMin 默认先在 两个全新副本中验证失败,只有 baseline 通过才开始缩减候选。
source_dir="/absolute/path/to/your/repository"
output_dir="/absolute/path/to/your/repository-repro"
failure_command="$("$project_python" -c 'import shlex, sys; print(shlex.join([sys.executable, "-m", "pytest", "-q", "tests/test_checkout.py"]))')"
failure_match='AssertionError: checkout total mismatch'
failure_exit_code=1
"$repomin_cli" reduce "$source_dir" \
--command "$failure_command" \
--match "$failure_match" \
--exit-code "$failure_exit_code" \
--max-attempts 25 \
--max-duration 300 \
--semantic-reducer none \
--output "$output_dir"这里沿用前面记住的项目解释器,并处理 Bash/Zsh 下路径含空格时的引号。
默认排除 .venv 和 venv,所以 .venv/bin/python -m pytest 这样的相对路径
在副本中找不到环境。缩减和重放时继续使用同一个 failure_command。
如果原仓库能运行、副本却失败,请参考
baseline 排错说明。
解释器的绝对路径属于本机环境,该环境不会随 payload 一起导出。向其他开发者
分享结果前,请先阅读重放要求。
如果环境中有项目的 editable 安装、同名包的已安装版本,或指向绝对路径的
PYTHONPATH,测试仍可能导入候选副本之外的代码。把
源码来源检查
放进复现命令,在每个候选和重放中都执行。baseline 通过或指纹一致,不能证明
测试使用的是候选源码。
输出目录和 <output>.repomin sidecar 都不能已存在,也不能位于源仓库内部。
失败命令本身仍可修改 backend 允许访问的任何资源;在默认 host backend 下,
它拥有当前用户的权限。
ReproMin 会导出预算内找到的最小已验证状态。大仓库第一次不必追求固定点;先看
有限预算的结果,再决定是否增加限制。需要强制保留 oracle 脚本、许可证或锁文件
时使用 --keep RELATIVE_PATH;只有当失败契约能拒绝无效内容时,才用
--text-file RELATIVE_PATH 对指定 UTF-8 文件按行缩减。
需要单独诊断准备状态时,可使用 Doctor。不传 --command 的静态
检查不会执行失败命令。
payload 和证据 sidecar 是两个独立目录:
<output>/ 缩减后的仓库
<output>.repomin/report.json 机器可读证据
<output>.repomin/REPOMIN.md 面向人的摘要
先在不执行失败命令的情况下验证报告和 payload:
"$repomin_cli" report validate \
"${output_dir}.repomin/report.json" \
--payload "$output_dir" \
--format markdown成功结果应包含 payload_fingerprint_verified: true。同时检查
payload_fingerprint_mode:exact 包含已记录的文件系统元数据;content
表示路径、条目类型、文件内容和符号链接目标一致,但没有证明元数据一致,artifact
传输改写元数据是常见原因之一。
检查 report.json 中记录的命令后,再明确允许在两个全新副本中重放:
"$repomin_cli" report replay \
"${output_dir}.repomin/report.json" \
--payload "$output_dir" \
--runs 2 \
--yes验证指纹不会执行命令;replay 只证明当前环境仍符合配置的失败契约。两者都不能 证明代码正确或找到根因。
人工检查后,把脱敏副本链接到对应 bug,加入回归测试,或保留为调试和依赖升级 样例。保留未经修改的 payload 和 sidecar 作为证据副本;如果为了 issue 增加 README 或恢复展示文件,请说明它已不同于指纹对应的版本,并重新执行失败命令。
不要公开凭据、私有 URL、专有源码、客户数据、原始日志、含密钥的命令或环境变量 值。可以在 Show and tell 分享成功、受阻或结论不明确的尝试。对于公开且许可证清晰的仓库,也可以在 pilot issue #11 提供 revision、复现命令、 失败签名和期望帮助,由维护者协助完成一次有限预算的试验。
默认 host backend 不是沙箱。只对可信仓库和命令使用它;Docker 可以缩小访问 范围,但也不是完整安全边界。处理第三方代码或分享结果前,请阅读 安全说明。其他生态示例、配置、GitHub Action 和报告文档见 文档索引。