Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
294 lines (209 loc) · 5.8 KB

CONTRIBUTING.md

File metadata and controls

294 lines (209 loc) · 5.8 KB
Raw

贡献指南

感谢您对 QuickBox 的关注！我们欢迎所有形式的贡献。

📋 目录

📜 行为准则

参与本项目时，请遵守以下行为准则：

  • 尊重所有贡献者
  • 接受建设性的批评
  • 关注对社区最有利的事情
  • 对其他社区成员表示同理心

🤝 如何贡献

报告问题

如果您发现了 bug 或有功能建议，请：

  1. 检查 Issues 是否已有相关问题
  2. 如果没有，请创建新 Issue，包含：
    • 清晰的问题描述
    • 复现步骤
    • 预期行为 vs 实际行为
    • 环境信息（厂商、框架版本等）
    • 相关代码或截图

提交代码

  1. Fork 本仓库
  2. 创建功能分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m 'feat: Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 开启 Pull Request

🛠️ 开发环境设置

前置要求

  • Node.js >= 14.0.0
  • npm 或 yarn
  • TypeScript 5.0+
  • Git

安装步骤

# 克隆仓库
git clone https://github.com/hackerFish/quickBox.git
cd quickBox

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试（如果有）
npm test

# 代码检查
npm run lint

开发模式

# 监听模式，自动编译
npm run dev

📝 代码规范

TypeScript 规范

  • 使用 TypeScript 编写所有代码
  • 遵循项目中的 tsconfig.json 配置
  • 为所有公共 API 提供类型定义
  • 使用明确的类型，避免 any

代码风格

  • 使用 2 空格缩进
  • 使用单引号
  • 行尾不加分号（根据项目配置）
  • 函数和类使用 PascalCase
  • 变量和函数参数使用 camelCase
  • 常量使用 UPPER_SNAKE_CASE

文件命名

  • 适配器文件：vendor.ts（如 oppo.ts, xiaomi.ts）
  • API 文件：api-name.ts（如 payment.ts, router.ts）
  • 工具文件：utility-name.ts（如 reader.ts, shortcut.ts）
  • 组件文件：ComponentName/index.ux

注释规范

  • 所有公共 API 必须有 JSDoc 注释
  • 复杂逻辑必须有行内注释
  • 使用中文注释（项目主要面向中文开发者）

示例：

/**
 * 创建激励视频广告实例
 * @param options 广告配置选项
 * @returns 广告实例
 */
export function createRewardedVideoAd(options: RewardedVideoAdOptions): RewardedVideoAdInstance {
  // 实现代码
}

📤 提交规范

我们使用 Conventional Commits 规范。

提交类型

  • feat: 新功能
  • fix: Bug 修复
  • docs: 文档更新
  • style: 代码格式调整（不影响功能）
  • refactor: 代码重构
  • perf: 性能优化
  • test: 测试相关
  • chore: 构建/工具链相关
  • ci: CI/CD 相关

提交格式

<type>(<scope>): <subject>

<body>

<footer>

示例

# 新功能
git commit -m "feat(payment): 添加华为支付支持"

# Bug 修复
git commit -m "fix(router): 修复华为 navigateToHome 问题"

# 文档更新
git commit -m "docs: 更新支付 API 文档"

# 多行提交信息
git commit -m "feat(ad): 添加激励视频广告支持

- 支持 OPPO、vivo、小米、华为
- 自动处理各厂商差异
- 添加完整类型定义"

Scope 说明

  • payment: 支付相关
  • ad: 广告相关
  • router: 路由相关
  • storage: 存储相关
  • account: 账号相关
  • device: 设备相关
  • adapter: 适配器相关
  • utils: 工具函数
  • components: 组件相关

🔄 Pull Request 流程

创建 PR 前

  1. ✅ 确保代码通过 npm run lint
  2. ✅ 确保代码通过 npm run build
  3. ✅ 更新相关文档
  4. ✅ 添加必要的测试（如果有）
  5. ✅ 更新 CHANGELOG.md（如果有重大变更）

PR 标题格式

使用与提交信息相同的格式：

feat(payment): 添加华为支付支持
fix(router): 修复华为 navigateToHome 问题

PR 描述模板

## 📝 变更说明
简要描述本次 PR 的变更内容

## 🔧 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 性能优化
- [ ] 文档更新
- [ ] 代码重构
- [ ] 其他

## ✅ 测试
- [ ] 已在 OPPO 设备测试
- [ ] 已在 vivo 设备测试
- [ ] 已在小米设备测试
- [ ] 已在华为设备测试
- [ ] 已在荣耀设备测试

## 📸 截图（如适用）
添加相关截图

## 🔗 相关 Issue
Closes #123

代码审查

  • PR 需要至少一位维护者审查通过
  • 审查者会检查代码质量、兼容性、文档完整性
  • 根据反馈进行修改后，请重新标记审查者

🎯 贡献方向

1. 新功能开发

  • 添加新的 API 支持
  • 实现新的适配器
  • 开发新的工具函数
  • 创建新的组件

2. Bug 修复

  • 修复兼容性问题
  • 修复 API 实现错误
  • 修复文档错误

3. 文档改进

  • 完善 API 文档
  • 添加使用示例
  • 编写教程文章
  • 翻译文档

4. 性能优化

  • 优化代码执行效率
  • 减少包体积
  • 优化内存使用

5. 测试覆盖

  • 添加单元测试
  • 添加集成测试
  • 添加兼容性测试

6. 代码质量

  • 重构冗余代码
  • 改进代码结构
  • 统一代码风格

🏆 贡献者

感谢所有为 QuickBox 做出贡献的开发者！

（贡献者列表会在项目成熟后自动生成）

📞 获取帮助

如果您在贡献过程中遇到问题：

再次感谢您的贡献！🎉