给 Slopsmith 贡献代码:Git 工作流、pytest 测试规范与插件 AGPL 许可政策全解读
给 Slopsmith 贡献代码:Git 工作流、pytest 测试规范与插件 AGPL 许可政策全解读
Slopsmith 是一个自托管的 Docker Web 应用,用于浏览、播放和练习全乐队交互式乐谱(吉他、贝斯、键盘、鼓、人声),并内置强大的插件系统。想给它贡献代码?本文完整解读三大核心——Git 工作流、pytest 测试规范、插件 AGPL 许可政策,帮你第一次提交 PR 就能顺利过审。
一、先认识 Slopsmith:代码在哪里,改什么看什么
Slopsmith 的后端是 FastAPI,前端是零框架的原生 JavaScript,整体结构非常清晰:
| 目录 / 文件 | 职责 |
|---|---|
| server.py | FastAPI 主入口:音乐库 API、WebSocket 音符高速路、插件加载 |
| static/ | 前端单页应用(app.js、highway.js、index.html) |
| lib/ | 共享 Python 库:乐谱解析、PSARC/Sloppak 格式、音频处理 |
| plugins/ | 插件系统,每个插件一个独立目录(常为独立 git 仓库) |
| tests/ | pytest 测试套件(Python 端在 tests/test_*.py,JS 端在 tests/js/) |
修改 lib/ 下的核心逻辑(如 lib/song.py 的乐谱数据模型、lib/psarc.py 的归档解析)前,建议先跑一遍对应测试,这是后文第三部分的重点。
二、Git 工作流:从 Fork 到 PR 的完整步骤
权威说明见 CONTRIBUTING.md,核心规则一句话:永远不要直接推 main,一切贡献走功能分支 + PR。
2.1 克隆仓库并配置双远程
git clone https://gitcode.com/gh_mirrors/sl/slopsmith.git slopsmith
cd slopsmith
git remote add upstream <上游仓库地址> # origin 是你的 fork,upstream 是主仓库
2.2 功能分支 + PR 流程
- 基于最新
main创建功能分支:git checkout -b fix/sloppak-art-path; - 提交改动,向
main发起 Pull Request; - 保持提交范围小、描述清楚;
- 如果改动影响用户可见行为,记得在 CHANGELOG.md 的
[Unreleased]段落补一条记录。
💡 版本号由 VERSION 文件统一管理,且由发布流程自动改写——贡献者不要手动改 VERSION,只需维护 CHANGELOG。
2.3 DCO 提交签名:git commit -s 一键搞定
Slopsmith 采用 Developer Certificate of Origin(DCO)追踪贡献来源,每个 commit 都必须签核:
git commit -s -m "fix: correct sloppak art path resolution"
-s 会在提交信息末尾追加一行:
Signed-off-by: Jane Developer <jane@example.com>
这行签名即代表你确认:代码是你写的(或有权提交)、且同意按 AGPL-3.0-only 许可分发。忘记签名也不用慌,对最近的提交执行 git commit --amend -s 补签后强推 PR 分支即可。
2.4 两个新手最容易踩的坑
- 提交信息风格:简短的命令式主题行(short imperative subject)+ 空行 + 解释 为什么 这么改的正文。
- 插件目录是 gitlink:
plugins/下每个插件通常是独立 git 仓库(submodule 或 clone),切换主仓库分支可能"误伤"插件目录。必要时对插件目录执行git update-index --assume-unchanged加以保护。
三、pytest 测试规范:本地跑测试的正确姿势
Slopsmith 用 pytest 做后端测试,配置全部集中在 pyproject.toml 中:
[tool.pytest.ini_options]
pythonpath = [".", "lib"] # lib/ 无 __init__.py,走平铺导入
testpaths = ["tests"]
addopts = "-v --tb=short"
其中 pythonpath = [".", "lib"] 是关键——lib/ 刻意不使用包结构,任何测试里都是平铺导入(如 from song import Song),无需相对路径或安装项目本身。
3.1 安装测试依赖
pip install -r requirements-test.txt
requirements-test.txt 包含 4 个依赖:pytest>=8.0、httpx>=0.27.0(API 测试客户端)、numpy 与 soundfile(歌词转写测试生成静音/响度 WAV 用,缺失时对应用例会经 pytest.importorskip 静默跳过)。
3.2 最常用的三条 pytest 命令
pytest # 跑全部测试
pytest tests/test_song.py -v # 跑单个测试文件
pytest -k "round_trip" -v # 按关键字过滤用例
addopts 已内置 -v --tb=short,输出默认详细且回栈简短,无需额外参数。
3.3 编写测试的注意事项
- 共享 fixture 在 tests/conftest.py:例如
isolate_logging会在每个测试前后保存/恢复slopsmith、uvicorn等 logger 的状态,避免日志配置的修改在测试之间互相污染——调用configure_logging()的测试模块建议复用它。 - 前端测试在 tests/js/:大量
highway_3d_*.test.js、playback_*.test.js覆盖音符高速路渲染与播放逻辑,浏览器端到端测试在 tests/browser/(Playwright 驱动,配置见 playwright.config.ts)。 - CI 会在每次推送到 main 或 PR 时自动运行 pytest(Python 3.12 环境),本地测试绿了再提 PR,能显著缩短评审往返。
四、许可政策全解读:AGPL-3.0 与插件许可证白名单
许可条款是贡献前最容易被忽略、却最不能出错的环节,权威出处同样是 CONTRIBUTING.md 与 LICENSE。
4.1 核心代码:inbound = outbound
Slopsmith 核心以 AGPL-3.0-only 许可发布。你提交的 PR、补丁、文档乃至精选插件列表条目,都按同一许可"入站即出站"(inbound = outbound)——发起 PR 即代表你同意贡献内容随 Slopsmith 以 AGPL-3.0-only 分发。DCO 签名中的"按 LICENSE 所述以 AGPL-3.0-only 贡献"正是这一原则的落款。
4.2 插件:被加载 ≠ 被 AGPL 感染
插件是独立的仓库,运行时以单独的 Python 模块 / 浏览器脚本加载,加载行为本身不构成 AGPL 传染性。但若要进入官方精选插件列表,许可证需满足以下白名单:
| ✅ 可收录 | ❌ 不收录 |
|---|---|
| AGPL-3.0-only / or-later | GPL-2.0-only |
| GPL-3.0-only / or-later | LGPL-2.1-only |
| LGPL-3.0-only / or-later | CDDL |
| MIT、ISC | EPL |
| BSD-2-Clause / BSD-3-Clause | 专有(proprietary)条款 |
| Apache-2.0 | |
| Unlicense / CC0-1.0 / 0BSD |
即使插件使用的是不被收录的许可证,你仍可自由发布和自分发——用户本地安装的任何插件 Slopsmith 都会加载,只是不会被主项目"官方推荐"。
4.3 拿不准就早提问
不确定某个贡献(尤其许可问题)是否符合项目预期时,开 Issue 或发起 Discussion 远比做完功再被拒要好得多。
五、贡献前检查清单
- [ ] 已从最新
main建功能分支,未直接推 main - [ ] 每个 commit 均带
Signed-off-by(git commit -s) - [ ] 提交信息为主题式短句 + 解释动机的正文
- [ ] 本地
pytest全绿,新逻辑有对应用例 - [ ] 用户可见行为变更已写入 CHANGELOG 的
[Unreleased] - [ ] 插件许可证在白名单内(若申请进精选列表)
按这份清单走完,你的 PR 就会是维护者最期待看到的那种:范围清晰、测试完备、许可干净。🎸


