参与 Mopidy 贡献：从提问、提 Issue 到提交高质量 Pull Request 的完整指南

本指南基于 Mopidy 仓库的 docs/contributing.rst 编写，梳理了从社区提问、帮助用户、提交 Issue，到发起 Pull Request（PR）的完整协作流程。无论你是想报一个 bug、提一个新功能，还是第一次为 Mopidy 贡献代码，读完本文你都能掌握提问的正确渠道、Issue 的提交规范、PR 的开发流程与质量门槛（代码风格、测试、文档、commit message），以及一套可直接复用的本地开发与验证工具链。

贡献不止写代码：先了解你可以帮上什么

Mopidy 是一个用 Python 编写的可扩展音乐服务器，其贡献形态多种多样。官方文档在贡献指南的开头就强调：帮助其他用户解决问题本身就是一种被高度重视的贡献。

在论坛和 #mopidy-users 聊天频道中参与用户支持，能带来三方面的收益：

• 新用户能得到更快、更好的帮助，社区的反馈循环更高效；
• 你在回答问题的过程中会迅速了解用户最容易困惑、最难上手、最欠缺的功能点，这些正是改进代码或文档的绝佳选题；
• 更多人分担用户支持工作后，核心贡献者可以把时间释放出来修 bug、做新功能。

因此，如果你暂时没有写代码的打算，从"回答别人的问题"开始进入 Mopidy 社区，是一条完全成立的贡献路径。

如何提问与获取帮助

贡献指南明确给出了两条官方求助渠道：

• Discourse 论坛（discourse.mopidy.com）：适合提出需要展开讨论、较复杂的问题；
• Zulip 聊天（#mopidy-users 频道，mopidy.zulipchat.com）：适合快速问答与实时交流。

在提问之前，建议先阅读仓库中的 排错指南。这样做有两个作用：一是你很可能自己就找到了解决方案；二是即使问题没有解决，你也已经掌握了如何提供有用的细节——比如 Mopidy 内置的 mopidy config（查看合并后的有效配置，密码等敏感值会被掩码）和 mopidy deps（列出所有依赖的路径与版本）这两个诊断命令的输出，以及 mopidy -vvvv 2>&1 | tee mopidy.log 抓取的完整调试日志。带上这些信息提问，能大幅提高别人帮你定位问题的效率。

Issue 指南：如何正确地报告 Bug 与提出功能请求

Mopidy 的 GitHub Issue 追踪器不是支持论坛，它只用于跟踪确认的 Bug 和功能请求。contributing.rst 给出了四步规范流程：

1. 需要帮助时，先走提问渠道（见上文），不要在 Issue 里直接求支持；
2. 不确定是不是 Bug 时，先在论坛发帖确认，避免把"用法问题"误报成"代码缺陷"；
3. 确认是 Bug 或有功能请求后，先检索已有 Issue，检查 Issue 追踪器中是否已存在相同问题；若已存在，看看能否补充有助于复现或修复的信息（如复现步骤、相关日志、错误消息）；
4. 没有匹配的 Issue 时再新建，并尽可能提供完整信息：若是 Bug，务必给出可复现步骤和相关的日志/报错内容。

这条流程的价值在于：一份信息充分的 Issue 能让维护者快速判断问题归属、复现路径和影响范围，也决定了它能否被高效地推进到修复阶段。

Pull Request 指南：从想法到合并的七步流程

contributing.rst 对 PR 的提交流程有明确要求，每一步都对应着仓库中的具体机制。以下按文档顺序展开，并补充仓库源码与配置层面的印证。

第一步：动手前先对齐想法

• Bug 修复：先按上文流程提交 Issue，让维护者确认问题确实存在；
• 功能增强：先在 GitHub Issue、论坛或 Zulip 上与其他 Mopidy 开发者讨论方案，确保你的想法与解决方案和社区方向一致。文档明确指出，这能"大幅提高 PR 被快速接受的概率"。

第二步：从 main 分支创建小而有主题的分支

每个功能或 Bug 修复都应当新建独立分支，且基于 main 分支。分支要保持小、聚焦单一主题，这样会"far easier to review"（更容易评审）。

这一点与仓库当前的开发分支策略一致：根据 变更日志 的记载，Mopidy 4.0 起已删除 develop 分支，所有开发统一在 main 分支上进行。所有新功能、修复都汇入 main，PR 的目标分支也是 main。更具体的 Git 操作（远程仓库命名、git checkout -b fix-crash-on-foo upstream/main 等）可以参考 开发环境指南 中的"Contribution workflow"章节。

第三步：遵循代码风格，保证 ruff 检查通过

Mopidy 的 代码风格指南 要求：

• 用 Ruff 自动格式化所有代码（使用默认配置）；
• 用 Ruff 自动排序 import（使用默认配置）；
• 尽可能消除 Ruff 产生的全部 lint 警告。

CI 会强制检查 PR 是否为"ruff clean"，不通过这些检查的 PR 不会被合并。Ruff 的规则在 pyproject.toml 的 [tool.ruff] 段中配置：select = ["ALL"]（启用全部规则），并针对文档、内部模块和测试目录设置了 per-file-ignores（例如测试目录放宽了注解、断言等规则）。本地验证方式有两种，二者等价：

tox -e ruff-lint      # 与 CI 一致的 lint 环境
ruff check .          # 直接运行 ruff

ruff format --check（对应 tox 的 ruff-format 环境）则用于校验格式化结果。少数确实不该被 ruff 警告的代码行，可以追加 # noqa: <warning code> 注释跳过检查，例如 src/mopidy/__main__.py 中就有 # noqa: F401 (imported to test GStreamer presence) 这类用法。

第四步：为任何新功能或实质性 Bug 修复补充测试

Mopidy 拥有相当高的测试覆盖率，要求所有新进入 Mopidy 的代码都自带测试。测试运行相关的全部细节见 开发环境指南 的 "Running tests" 章节，核心命令如下：

tox                 # 终极命令：运行与 CI 完全相同的全套检查
tox -e py311        # 只跑 Python 3.11 单元测试
pytest              # 直接以 pytest 运行全部测试
pytest tests/http/  # 只跑单个目录的测试，节省时间
pytest -n 4         # 借助 pytest-xdist 用 4 个进程并行，通常可省一半以上时间
pytest -f           # 监听文件变化，失败即停，适合快速迭代（--looponfail）
pytest --cov=mopidy --cov-report=term-missing   # 查看测试覆盖率明细
pytest --durations=10   # 列出最慢的 10 个测试

测试基础设施在 pyproject.toml 中也有体现：[tool.tox.env_run_base] 定义的标准命令是 pytest --basetemp={envtmpdir} --cov=mopidy --cov-report=term-missing，测试矩阵覆盖 Python 3.11、3.12、3.13 以及 docs、pyright、ruff-lint、ruff-format 等环境。仓库的测试代码位于 tests/ 目录，覆盖了 core、audio、http、m3u、stream、config、models 等全部核心模块。

第五步：为新功能编写文档

任何新功能都必须包含文档。Mopidy 使用 Sphinx 构建文档（配置见 docs/conf.py），本地构建方式如下：

cd docs/
make html
# 生成结果在 _build/html/index.html，可用 xdg-open（Linux）或 open（macOS）打开

文档目录采用 Graphviz 生成部分架构图，因此构建前可能需要安装 graphviz 包（如 sudo apt install graphviz）。文档的完整工作流（含 Read the Docs 自动构建）见 开发环境指南 的 "Writing documentation" 章节。

第六步：可选的变更日志条目

欢迎在 PR 中附带一条 changelog 记录。Mopidy 的变更日志位于 docs/changelog.rst，按照版本分组记录依赖变更、Core/Backend/Audio API 变更、扩展支持与内部实现等分类。历史版本日志则在 docs/history/ 目录中。例如 4.0.0 条目中记录的 "Dropped split between the main and develop branches"、"Switched from mypy to pyright for type checking" 等内部变更，都直接反映了当前仓库的开发策略。

第七步：写好 commit message

contributing.rst 对 commit message 有三点具体要求：

1. 首行遵循 "topic: description" 模板，例如 mpd: Switch list command to using list_distinct。第一行用冒号分隔的主题与描述，便于扫读历史；
2. 用其余部分解释任何不显然的内容：细节写进 commit message 而不是 PR 描述，因为"commit message 会永远存在"；
3. 用祈使句、现在时：写 "add" 而不是 "added"。

完成以上七步后，将分支推送到自己的 fork，向 main 分支发起 PR。PR 创建后，GitHub Actions CI 会自动运行全部测试；任何 CI 构建不绿的 PR 都不会被合并，因此收到失败通知后应尽快修复，并通过向同一分支继续 push 来更新 PR。

本地开发环境的搭建要点

虽然 contributing.rst 本身聚焦流程，但要真正把 PR 指南落地，需要一套可用的本地开发环境。开发环境指南 提供了推荐的完整方案，其要点与 PR 指南环环相扣：

1. 先常规安装 Mopidy：Mopidy 有一些非 Python 依赖（如 GStreamer），建议先按 安装文档 完整安装一遍，作为"始终可用的兜底"；
2. 创建独立 virtualenv：python3 -m venv ~/mopidy-dev/.venv，开发、依赖升级都在虚拟环境内进行，不影响系统安装；
3. 以 editable 模式安装：pip install --upgrade --editable .。源码不会拷贝进 site-packages，而是建立指向 Git 仓库的链接——改完代码重启 Mopidy 即可生效，无需重新安装；
4. 安装开发工具：pip install --upgrade --editable ".[dev]"，其中 [dev] 对应的依赖组在 pyproject.toml 中定义为 ["mopidy[docs,lint,test,typing]", "tox >= 4.21"]；
5. 了解扩展注册机制：editable 安装会通过 importlib 注册 Mopidy 自带的扩展。安装后虚拟环境中的 Mopidy-*.dist-info/entry_points.txt 会展示 mopidy 可执行入口和五个内置扩展（file、http、m3u、softwaremixer、stream）的映射，这与 pyproject.toml 中的 <a href="https://link.gitcode.com/i/e375b76f58eefcc9bebee29aa8ca8c10" target="_blank">project.entry-points."mopidy.ext"] 声明一一对应。入口加载逻辑见 [src/mopidy/main.py：它先通过 ext.load_extensions() 扫描入口点，再依据用户配置决定各扩展的启用/禁用状态。

排错与调试工具：贡献过程中自证自检

PR 指南要求你"自己先验证"，Mopidy 内置的诊断工具正好服务于这个目的（详见 排错指南）：

场景	命令
查看合并后的有效配置（敏感值已掩码）	mopidy config（服务场景：sudo mopidyctl config）
列出全部依赖的路径与版本	mopidy deps（服务场景：sudo mopidyctl deps）
抓取调试日志	mopidy -vvvv 2>&1 | tee mopidy.log，或配置 [logging] verbosity = 4
查看单曲元数据	python3 -m mopidy.audio.scan path_to_your_file
排查死锁	pkill -SIGUSR1 mopidy（主线程会 dump 所有线程的 traceback）
调试 GStreamer	GST_DEBUG=3 mopidy -v、GST_DEBUG_DUMP_DOT_DIR=. mopidy 等环境变量

在提交 PR 前，使用这些工具确认自己的改动没有引入配置、依赖或运行时问题，能让 PR 的评审过程顺畅得多。

总结：一份可执行的贡献清单

把 contributing.rst 的流程浓缩为提交 PR 前的自查清单：

1. 已与社区确认这是 bug 还是合理的新功能？
2. 分支基于 main 创建，且小而聚焦？
3. tox（或至少 tox -e ruff-lint、ruff format --check）全部通过，ruff clean？
4. 新功能/实质性修复附带测试，且本地 pytest 通过？
5. 新功能附带 Sphinx 文档并能成功 make html？
6. 如有必要，在 docs/changelog.rst 加了 changelog 条目？
7. 每个 commit 首行遵循 "topic: description"，正文用祈使句现在时？

对照这份清单走完流程，你的 PR 就具备了与 Mopidy CI 和质量标准对齐的基础。相关文档与配置的完整路径如下：贡献总则见 docs/contributing.rst，开发环境与工具链见 docs/devenv.rst，代码风格见 docs/codestyle.rst，排错工具见 docs/troubleshooting.rst，工具链声明集中在 pyproject.toml。