MeBox/CONTRIBUTING.md

贡献规范

感谢你愿意帮助 MeBox 变得更稳定。这个项目主要面向 NAS、Docker 部署、媒体库整理、订阅下载和多端播放场景；提交 Issue 或 Pull Request 时，请尽量提供可复现、可验证的信息。

Issue 提交规范

提交 Issue 前，请先确认：

• 已搜索现有 Issues，避免重复提交同一个问题。
• 使用的是最新镜像、最新主分支，或已说明当前版本号 / 镜像摘要。
• 如果是部署或运行问题，已附上部署方式和关键配置。

Bug Report 必填信息

• 问题现象：实际发生了什么，是否稳定复现。
• 期望行为：你认为正确结果应该是什么。
• 复现步骤：从哪个页面、点击什么、填写什么、触发什么任务。
• 部署方式：Docker 第一档 / 第二档 / 第三档、裸机运行、反代方式等。
• 环境信息：NAS 型号或系统、Docker / Compose 版本、浏览器、MeBox 镜像版本。
• 相关配置：路径映射、下载器保存路径、媒体库路径、站点类型等。请隐藏 Cookie、API Key、密码和 Token。
• 日志和任务信息：优先提供应用日志、任务队列详情、浏览器控制台错误、网络请求错误。

日志建议

排查订阅、站点搜索、下载器、整理入库、网盘扫描时，建议临时把日志级别调整为 info 或 debug，复现后再恢复。

Docker 部署常用命令：

docker compose ps
docker compose logs --tail=300 mebox
docker compose exec mebox sh -lc 'ls -la /data/logs || true'

PostgreSQL 部署查询示例：

docker compose exec postgres psql -U mebox -d mebox -c "select key,value,updated_at from settings order by updated_at desc limit 30;"

请勿公开粘贴以下敏感信息：

• 站点 Cookie、Passkey、API Key、YemaPT Auth Key、M-Team API Key。
• qBittorrent / Transmission / Aria2 密码。
• Telegram Bot Token。
• JWT、数据库密码、私有下载链接。

Pull Request 提交规范

所有非紧急变更都应通过 Pull Request 合入 main，不要直接向主分支推送。贡献者可以从 fork 或本仓库的独立分支发起 PR；维护者只有在紧急安全修复、发布流水线修复等特殊场景下，才可以短暂绕过 PR 流程，并需要在提交说明或后续 Issue 中补充原因。

PR 应该尽量小而清晰。一次 PR 聚焦一个问题或一组强相关改动，避免把无关重构、格式化和功能混在一起。

分支要求

• 分支从最新 main 创建，提交前先同步远端主分支。
• 分支名建议使用 fix/...、feat/...、docs/... 或 test/...。
• 不要在 main 上直接开发和提交 PR 内容。
• 不要把个人部署配置、NAS 本地路径、私有镜像标签或测试数据提交进 PR。
• 如果基于魔改版、私有部署版或临时补丁开发，请先确认改动能在本仓库最新 main 上复现和应用，再提交 PR。

PR 描述应包含

• 背景：修复哪个 Issue / 哪个用户场景 / 哪个回归。
• 改动摘要：后端、前端、配置、文档分别改了什么。
• 验证结果：运行过哪些命令，是否有无法运行的测试。
• 风险说明：数据迁移、Docker 配置、路径映射、下载器行为、站点 API 限流等是否受影响。
• 截图或录屏：涉及 UI、任务队列、错误提示、设置页时请附上。

推荐验证命令

根据改动范围选择运行：

go test ./...
npm --prefix web run build
git diff --check

如果只改动某个模块，可以先跑定向测试，例如：

go test ./internal/service -run "TestOrganize|TestSubscription|TestMTeam" -count=1
go test ./cmd/server -count=1

代码要求

• Go 代码使用 gofmt。
• 前端 TypeScript 需要通过 npm --prefix web run build。
• 用户可见错误需要可操作：说明失败原因、下一步怎么查或怎么修。
• 后台任务失败不要静默吞掉，应进入任务队列、日志或 API 响应。
• Docker/NAS 路径相关改动必须考虑宿主机路径与容器路径映射。
• 站点 API、订阅和下载器改动需要注意去重、限流、敏感信息脱敏。

Commit Message 建议

优先使用简短清晰的动词开头：

fix organizer hardlink diagnostics
feat(yemapt): add auth-only site adapter
docs: add issue and pull request guidelines
test: cover subscription restore matching

维护者合并检查

合并前建议确认：

• PR 范围清楚，没有夹带无关改动。
• 自动化检查通过，或失败原因已说明。
• 修改涉及的用户路径已有日志、错误提示或回归测试。
• 文档、示例配置和 README 是否需要同步更新。