给 Slopsmith 贡献代码:Git 工作流、pytest 测试规范与插件 AGPL 许可政策全解读

原创2026-10-13 22:56:572,343 阅读

给 Slopsmith 贡献代码:Git 工作流、pytest 测试规范与插件 AGPL 许可政策全解读

Slopsmith 是一个自托管的 Docker Web 应用,用于浏览、播放和练习全乐队交互式乐谱(吉他、贝斯、键盘、鼓、人声),并内置强大的插件系统。想给它贡献代码?本文完整解读三大核心——Git 工作流、pytest 测试规范、插件 AGPL 许可政策,帮你第一次提交 PR 就能顺利过审。

Slopsmith 贡献代码前的界面预览:音乐库网格视图

一、先认识 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 的归档解析)前,建议先跑一遍对应测试,这是后文第三部分的重点。

Slopsmith 播放器与 2D 音符高速路界面

二、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 流程

  1. 基于最新 main 创建功能分支:git checkout -b fix/sloppak-art-path;
  2. 提交改动,向 main 发起 Pull Request;
  3. 保持提交范围小、描述清楚;
  4. 如果改动影响用户可见行为,记得在 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),无需相对路径或安装项目本身。

Slopsmith 3D Highway 插件:渲染逻辑同样受测试覆盖

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 就会是维护者最期待看到的那种:范围清晰、测试完备、许可干净。🎸

登录后查看全文
slopsmith