mirror of
https://github.com/truewhile/MeBox.git
synced 2026-09-28 03:06:38 +08:00
docs: add contribution guidelines
This commit is contained in:
ShukeBta
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: Bug 反馈
|
||||
about: 报告可复现的问题、报错、功能异常或回归
|
||||
title: "[Bug] "
|
||||
labels: bug
|
||||
assignees: ""
|
||||
---
|
||||
|
||||
## 问题现象
|
||||
|
||||
请描述实际发生了什么。
|
||||
|
||||
## 期望行为
|
||||
|
||||
请描述你认为正确结果应该是什么。
|
||||
|
||||
## 复现步骤
|
||||
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
||||
## 部署方式
|
||||
|
||||
- 部署方式：Docker 第一档 / 第二档 / 第三档 / 裸机 / 其他
|
||||
- 镜像或版本：
|
||||
- NAS / 系统：
|
||||
- Docker 版本：
|
||||
- Docker Compose 版本：
|
||||
- 浏览器：
|
||||
|
||||
## 关键配置
|
||||
|
||||
请贴出相关配置片段，例如路径映射、媒体库路径、下载器保存路径、站点类型等。
|
||||
|
||||
请务必隐藏 Cookie、API Key、Passkey、密码、Token 和私有下载链接。
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml 相关片段
|
||||
```
|
||||
|
||||
## 日志 / 任务详情
|
||||
|
||||
请附上应用日志、任务队列详情、浏览器控制台错误或网络请求错误。
|
||||
|
||||
```text
|
||||
|
||||
```
|
||||
|
||||
## 补充信息
|
||||
|
||||
截图、录屏、相关 Issue、你已经尝试过的排查步骤。
|
||||
@@ -0,0 +1,5 @@
|
||||
blank_issues_enabled: true
|
||||
contact_links:
|
||||
- name: Telegram MediaStationGo 交流群
|
||||
url: https://t.me/MediaStationGo
|
||||
about: 适合快速交流部署经验、使用问题和排查线索。
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
name: 功能建议
|
||||
about: 提出新功能、体验改进或兼容性需求
|
||||
title: "[Feature] "
|
||||
labels: enhancement
|
||||
assignees: ""
|
||||
---
|
||||
|
||||
## 需求背景
|
||||
|
||||
这个功能解决什么问题？当前使用流程哪里不方便？
|
||||
|
||||
## 期望方案
|
||||
|
||||
请描述你希望 MediaStationGo 如何工作。
|
||||
|
||||
## 使用场景
|
||||
|
||||
- 部署环境：
|
||||
- 相关页面或模块：
|
||||
- 受影响用户：
|
||||
|
||||
## 可接受的替代方案
|
||||
|
||||
如果有其他实现方式或临时解决办法，也请写出来。
|
||||
|
||||
## 补充信息
|
||||
|
||||
截图、竞品参考、API 文档、相关讨论链接等。
|
||||
@@ -0,0 +1,40 @@
|
||||
## 背景
|
||||
|
||||
说明这个 PR 解决的问题、关联 Issue 或用户场景。
|
||||
|
||||
> 请确认本 PR 基于本仓库最新 `main` 的独立分支或 fork 分支提交，未直接向 `main` 推送，也未夹带个人部署魔改配置。
|
||||
|
||||
## 改动摘要
|
||||
|
||||
-
|
||||
|
||||
## 验证
|
||||
|
||||
- [ ] `go test ./...`
|
||||
- [ ] `npm --prefix web run build`
|
||||
- [ ] `git diff --check`
|
||||
- [ ] 其他：
|
||||
|
||||
## 风险与兼容性
|
||||
|
||||
- 是否影响 Docker / NAS 路径映射：
|
||||
- 是否影响数据库迁移或数据结构：
|
||||
- 是否影响下载器、订阅、站点 API 或限流：
|
||||
- 是否包含敏感信息脱敏：
|
||||
|
||||
## 截图 / 日志
|
||||
|
||||
涉及 UI、任务队列、错误提示、设置页时请附截图或日志片段。
|
||||
|
||||
```text
|
||||
|
||||
```
|
||||
|
||||
## 提交前检查
|
||||
|
||||
- [ ] 分支已同步最新 `main`，不是直接在 `main` 上提交。
|
||||
- [ ] PR 范围聚焦，没有夹带无关重构。
|
||||
- [ ] 未提交个人部署配置、私有路径、API Key、Cookie、Token 或私有镜像标签。
|
||||
- [ ] 用户可见错误有清晰提示或日志。
|
||||
- [ ] 新行为有测试覆盖，或已说明无法覆盖的原因。
|
||||
- [ ] 文档、示例配置、README 已按需同步。
|
||||
+114
@@ -0,0 +1,114 @@
|
||||
# 贡献规范
|
||||
|
||||
感谢你愿意帮助 MediaStationGo 变得更稳定。这个项目主要面向 NAS、Docker 部署、媒体库整理、订阅下载和多端播放场景；提交 Issue 或 Pull Request 时，请尽量提供可复现、可验证的信息。
|
||||
|
||||
## Issue 提交规范
|
||||
|
||||
提交 Issue 前，请先确认：
|
||||
|
||||
- 已搜索现有 Issues，避免重复提交同一个问题。
|
||||
- 使用的是最新镜像、最新主分支，或已说明当前版本号 / 镜像摘要。
|
||||
- 如果是部署或运行问题，已附上部署方式和关键配置。
|
||||
|
||||
### Bug Report 必填信息
|
||||
|
||||
- 问题现象：实际发生了什么，是否稳定复现。
|
||||
- 期望行为：你认为正确结果应该是什么。
|
||||
- 复现步骤：从哪个页面、点击什么、填写什么、触发什么任务。
|
||||
- 部署方式：Docker 第一档 / 第二档 / 第三档、裸机运行、反代方式等。
|
||||
- 环境信息：NAS 型号或系统、Docker / Compose 版本、浏览器、MediaStationGo 镜像版本。
|
||||
- 相关配置：路径映射、下载器保存路径、媒体库路径、站点类型等。请隐藏 Cookie、API Key、密码和 Token。
|
||||
- 日志和任务信息：优先提供应用日志、任务队列详情、浏览器控制台错误、网络请求错误。
|
||||
|
||||
### 日志建议
|
||||
|
||||
排查订阅、站点搜索、下载器、整理入库、网盘扫描时，建议临时把日志级别调整为 `info` 或 `debug`，复现后再恢复。
|
||||
|
||||
Docker 部署常用命令：
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
docker compose logs --tail=300 mediastation-go
|
||||
docker compose exec mediastation-go sh -lc 'ls -la /data/logs || true'
|
||||
```
|
||||
|
||||
PostgreSQL 部署查询示例：
|
||||
|
||||
```bash
|
||||
docker compose exec postgres psql -U mediastation -d mediastation -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、任务队列、错误提示、设置页时请附上。
|
||||
|
||||
### 推荐验证命令
|
||||
|
||||
根据改动范围选择运行：
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
npm --prefix web run build
|
||||
git diff --check
|
||||
```
|
||||
|
||||
如果只改动某个模块，可以先跑定向测试，例如：
|
||||
|
||||
```bash
|
||||
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 建议
|
||||
|
||||
优先使用简短清晰的动词开头：
|
||||
|
||||
```text
|
||||
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 是否需要同步更新。
|
||||
Reference in New Issue
Block a user