246 lines
5.5 KiB
Markdown
246 lines
5.5 KiB
Markdown
# 贡献指南
|
|
|
|
感谢您对 Xget 的关注！我们欢迎各种形式的贡献，包括但不限于代码、文档、测试、反馈和建议。
|
|
|
|
## 🤝 贡献方式
|
|
|
|
### 报告问题
|
|
|
|
- 使用
|
|
[Issue 模板](https://github.com/xixu-me/Xget/issues/new/choose)报告 bug 或提出功能请求
|
|
- 搜索现有 issues 避免重复报告
|
|
- 提供详细的重现步骤和环境信息
|
|
|
|
### 提交代码
|
|
|
|
- fork 存储库到您的 GitHub 账户
|
|
- 创建功能分支 (`git checkout -b feature/amazing-feature`)
|
|
- 安装依赖以启用本地 Git hooks (`npm install`)
|
|
- 使用 Conventional
|
|
Commits 提交更改 (`git commit -m 'feat(platforms): add amazing feature'`)
|
|
- 推送到分支 (`git push origin feature/amazing-feature`)
|
|
- 创建 Pull Request
|
|
|
|
### 改进文档
|
|
|
|
- 修正文档中的错误或不准确信息
|
|
- 添加使用示例和最佳实践
|
|
- 翻译文档到其他语言
|
|
- 改进代码注释和 API 文档
|
|
|
|
## 🛠️ 开发环境设置
|
|
|
|
### 前置要求
|
|
|
|
- Node.js 18+
|
|
- npm 或 yarn
|
|
- Git
|
|
- Cloudflare 账户（用于测试部署）
|
|
|
|
### 本地开发
|
|
|
|
```bash
|
|
# 克隆存储库
|
|
git clone https://github.com/xixu-me/Xget.git
|
|
cd Xget
|
|
|
|
# 安装依赖
|
|
npm install
|
|
|
|
# 安装后会自动启用 commit-msg hook
|
|
|
|
# 启动开发服务器
|
|
npm run dev
|
|
|
|
# 单次运行测试
|
|
npm run test:run
|
|
|
|
# 代码格式化
|
|
npm run format
|
|
|
|
# 代码检查
|
|
npm run lint
|
|
```
|
|
|
|
## 📝 代码规范
|
|
|
|
### 代码风格
|
|
|
|
- 使用 2 个空格缩进
|
|
- 使用分号结尾
|
|
- 使用单引号字符串
|
|
- 遵循 ESLint 配置规则
|
|
|
|
### 命名约定
|
|
|
|
- 变量和函数使用 camelCase
|
|
- 常量使用 UPPER_SNAKE_CASE
|
|
- 类名使用 PascalCase
|
|
- 文件名使用 kebab-case
|
|
|
|
### 注释规范
|
|
|
|
```javascript
|
|
/**
|
|
* 函数描述
|
|
* @param {string} param1 - 参数1描述
|
|
* @param {Object} param2 - 参数2描述
|
|
* @returns {Promise<Response>} 返回值描述
|
|
*/
|
|
function exampleFunction(param1, param2) {
|
|
// 实现逻辑
|
|
}
|
|
```
|
|
|
|
## 🧪 测试
|
|
|
|
### 测试类型
|
|
|
|
- **单元测试**: 测试单个函数和模块
|
|
- **集成测试**: 测试组件间的交互
|
|
- **端到端测试**: 测试完整的用户场景
|
|
|
|
### 运行测试
|
|
|
|
```bash
|
|
# 单次运行所有测试
|
|
npm run test:run
|
|
|
|
# 运行特定测试文件
|
|
npm run test:run test/platforms/jenkins.test.js
|
|
|
|
# 按测试名称筛选
|
|
npm run test:run -- --testNamePattern "platform"
|
|
|
|
# 生成测试覆盖率报告
|
|
npm run test:coverage
|
|
```
|
|
|
|
### 编写测试
|
|
|
|
- 为新功能编写相应的测试
|
|
- 确保测试覆盖率不低于 80%
|
|
- 使用描述性的测试名称
|
|
- 测试边界情况和错误处理
|
|
|
|
## 🚀 提交规范
|
|
|
|
### Commit 消息格式
|
|
|
|
使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
|
|
|
|
```
|
|
<type>[optional scope]: <description>
|
|
|
|
[optional body]
|
|
|
|
[optional footer(s)]
|
|
```
|
|
|
|
### 类型说明
|
|
|
|
- `feat`: 新功能
|
|
- `fix`: 修复 bug
|
|
- `docs`: 文档更新
|
|
- `style`: 代码格式化（不影响功能）
|
|
- `refactor`: 代码重构
|
|
- `perf`: 性能优化
|
|
- `test`: 测试相关
|
|
- `chore`: 构建过程或辅助工具的变动
|
|
|
|
### 示例
|
|
|
|
```bash
|
|
feat(platforms): add support for Bitbucket
|
|
fix(cache): resolve cache invalidation issue
|
|
docs(readme): update installation instructions
|
|
perf(proxy): optimize request handling performance
|
|
```
|
|
|
|
### 自动校验
|
|
|
|
- `npm install` 会自动安装 `commit-msg` hook，在本地阻止不符合规范的提交
|
|
- GitHub Actions 会在 `push` 和 `pull_request`
|
|
中再次校验提交消息，防止绕过本地 hook
|
|
|
|
## 🔍 Pull Request 流程
|
|
|
|
### 提交前检查
|
|
|
|
- [ ] 代码通过所有测试
|
|
- [ ] 代码符合存储库规范
|
|
- [ ] 添加了必要的测试
|
|
- [ ] 更新了相关文档
|
|
- [ ] Commit 消息符合规范
|
|
|
|
### PR 描述模板
|
|
|
|
请使用 [PR 模板](.github/pull_request_template.md)填写详细信息。
|
|
|
|
### 代码审查
|
|
|
|
- 所有 PR 需要至少一个维护者的审查
|
|
- 解决审查中提出的问题
|
|
- 保持 PR 的焦点明确，避免混合多个不相关的更改
|
|
|
|
## 🌟 贡献认可
|
|
|
|
### 贡献者列表
|
|
|
|
我们会在 README.md 中维护贡献者列表，感谢每一位贡献者的付出。
|
|
|
|
### 贡献统计
|
|
|
|
- 代码贡献会在 GitHub 贡献图中显示
|
|
- 重要贡献会在 Release Notes 中特别提及
|
|
- 长期贡献者可能被邀请成为存储库维护者
|
|
|
|
## 📋 开发任务
|
|
|
|
### 当前优先级
|
|
|
|
1. **性能优化**: 提升缓存效率和响应速度
|
|
2. **平台支持**: 添加新的代码托管和包管理平台
|
|
3. **安全增强**: 加强请求验证和安全防护
|
|
4. **监控改进**: 完善性能监控和错误追踪
|
|
|
|
### 适合新手的任务
|
|
|
|
查找标有 `good first issue` 标签的 issues，这些通常是：
|
|
|
|
- 文档改进
|
|
- 简单的 bug 修复
|
|
- 代码格式化
|
|
- 测试用例添加
|
|
|
|
## 🤔 获取帮助
|
|
|
|
### 沟通渠道
|
|
|
|
- **GitHub Issues**: 报告问题和功能请求
|
|
- **Email**: 敏感问题可发送至维护者邮箱
|
|
|
|
### 常见问题
|
|
|
|
**Q: 如何添加新平台支持？** A: 在 `src/config/platform-catalog.js`
|
|
中添加平台地址；如果需要特殊路径转换，再更新
|
|
`src/routing/platform-transformers.js`，然后补充相关文档和测试。
|
|
|
|
**Q: 如何测试 Cloudflare Workers 功能？** A: 使用 `npm run dev`
|
|
启动本地开发服务器，或部署到 Cloudflare Workers 测试环境。
|
|
|
|
**Q: 如何处理跨域问题？** A: 检查 CORS 配置，确保允许的源和方法设置正确。
|
|
|
|
## 📄 许可证
|
|
|
|
通过贡献代码，您同意您的贡献将在与存储库相同的 [AGPL-3.0 许可证](LICENSE)
|
|
下发布。
|
|
|
|
## 🙏 致谢
|
|
|
|
感谢所有为 Xget 做出贡献的开发者、测试者和用户。您的支持和反馈是存储库持续改进的动力！
|
|
|
|
---
|
|
|
|
如果您有任何问题或建议，请随时通过 GitHub Issues 与我们联系。我们期待您的参与！
|