Skip to content

贡献指南

Jump to bottom
lintsinghua edited this page Oct 26, 2025 · 1 revision

🤝 贡献指南

感谢你考虑为 XCodeReviewer 做贡献！每一个贡献都很重要

🌟 贡献方式

有很多方式可以为项目做贡献，不一定要写代码：

  • 🐛 报告Bug - 帮助我们发现和修复问题
  • 💡 提出新功能 - 分享你的想法和建议
  • 📝 改进文档 - 让文档更清晰易懂
  • 💻 提交代码 - 修复bug或开发新功能
  • ⭐ Star项目 - 给予项目支持和关注
  • 📢 推广项目 - 告诉更多人这个工具

🐛 报告Bug

报告前的检查

在提交新issue前，请先：

  1. ✅ 搜索已有Issues - 可能已经有人报告过
  2. ✅ 确认是Bug - 而不是使用方法的问题
  3. ✅ 尝试最新版本 - 可能已经修复了
  4. ✅ 查阅文档 - 常见问题 可能有答案

如何报告

访问： GitHub Issues

选择模板： Bug Report

填写内容：

## Bug描述
简洁清晰地描述问题

## 复现步骤
1. 进入'...'
2. 点击'...'
3. 看到错误

## 期望行为
应该发生什么

## 实际行为
实际发生了什么

## 截图
如果可能，添加截图

## 环境信息
- 操作系统：[如 macOS 13.0]
- 浏览器：[如 Chrome 120]
- 部署方式：[Docker/本地开发]
- 版本：[如 v1.1.0]

## 额外信息
- 控制台错误信息
- 相关日志

小技巧：

  • 📸 截图比文字描述更清楚
  • 📋 贴日志时用代码块（```）包裹
  • 🎯 问题越具体，越容易被修复

💡 提出新功能

提议前的思考

  1. 这个功能对多数用户有用吗？
  2. 是否与项目目标一致？
  3. 实现复杂度如何？

如何提议

访问： GitHub Issues

选择模板： Feature Request

填写内容：

## 功能描述
清晰描述你想要的功能

## 使用场景
为什么需要这个功能？解决什么问题？

例如：
作为一个[用户角色]
我想要[做什么]
以便[达到什么目的]

## 建议的实现
（可选）你觉得如何实现？

## 备选方案
（可选）还有其他解决方案吗？

## 额外信息
- 参考示例
- 竞品对比
- 截图/原型

💻 贡献代码

开发流程

1. Fork 项目
   ↓
2. 创建特性分支
   ↓
3. 编写代码
   ↓
4. 提交代码
   ↓
5. 推送到你的Fork
   ↓
6. 创建Pull Request
   ↓
7. Code Review
   ↓
8. 合并到主分支

详细步骤

第1步：Fork项目

访问 XCodeReviewer，点击右上角 "Fork" 按钮

第2步：克隆你的Fork

# 克隆你Fork的仓库
git clone https://github.com/你的用户名/XCodeReviewer.git

# 进入目录
cd XCodeReviewer

# 添加上游仓库
git remote add upstream https://github.com/lintsinghua/XCodeReviewer.git

# 验证
git remote -v
# 应该看到 origin (你的Fork) 和 upstream (官方仓库)

第3步：创建特性分支

# 确保主分支是最新的
git checkout main
git pull upstream main

# 创建并切换到特性分支
git checkout -b feature/你的功能名

# 例如：
git checkout -b feature/add-python-support
git checkout -b fix/issue-123

分支命名规范：

  • feature/xxx - 新功能
  • fix/xxx - Bug修复
  • docs/xxx - 文档更新
  • refactor/xxx - 代码重构
  • test/xxx - 测试相关

第4步：编写代码

开发前：

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

编码规范：

  1. 遵循现有代码风格

    # 运行代码检查
pnpm lint

# 自动修复格式问题
pnpm lint:fix

  2. 添加类型定义

    // ✅ 好
interface User {
  id: string;
  name: string;
}

function getUser(id: string): User {
  // ...
}

// ❌ 避免
function getUser(id): any {
  // ...
}

  3. 编写注释

    /**
 * 分析代码质量
 * @param code 要分析的代码
 * @param language 编程语言
 * @returns 分析结果
 */
async function analyzeCode(
  code: string, 
  language: string
): Promise<AnalysisResult> {
  // ...
}

  4. 保持组件简洁

    // 一个组件最好不超过200行
// 复杂逻辑提取为Hook
// 复杂UI拆分为子组件

测试你的改动：

# 类型检查
pnpm type-check

# 代码检查
pnpm lint

# 构建测试
pnpm build

第5步：提交代码

提交规范：

使用 Conventional Commits 格式：

类型(范围): 简短描述

详细描述（可选）

相关Issue: #123

类型：

  • feat: 新功能
  • fix: Bug修复
  • docs: 文档更新
  • style: 代码格式（不影响功能）
  • refactor: 重构
  • test: 测试相关
  • chore: 构建/工具相关

示例：

# 新功能
git commit -m "feat(analysis): 添加Python代码分析支持"

# Bug修复
git commit -m "fix(ui): 修复暗黑模式下按钮颜色问题

关闭 #123
"

# 文档更新
git commit -m "docs(wiki): 更新快速开始指南"

提交前检查：

# 确保没有遗漏文件
git status

# 查看改动
git diff

# 添加文件
git add .
# 或选择性添加
git add src/components/MyComponent.tsx

# 提交
git commit -m "feat: 你的提交信息"

第6步：推送到你的Fork

# 首次推送
git push -u origin feature/你的功能名

# 后续推送
git push

第7步：创建Pull Request

  1. 访问你的Fork 在GitHub上
  2. 会看到提示 "Compare & pull request"，点击它
  3. 填写PR信息：
## 改动描述
简要说明这个PR做了什么

## 改动类型
- [ ] Bug修复
- [ ] 新功能
- [ ] 文档更新
- [ ] 代码重构
- [ ] 其他

## 关联Issue
解决 #123

## 测试
- [ ] 已通过 `pnpm lint`
- [ ] 已通过 `pnpm type-check`
- [ ] 已通过 `pnpm build`
- [ ] 已在浏览器中测试

## 截图
（如果是UI改动，添加截图）

## 额外说明
其他需要说明的内容
  1. 点击 "Create Pull Request"

第8步：Code Review

维护者会：

  • 📖 审查代码
  • 💬 提出修改建议
  • ✅ 批准或请求更改

你需要：

  • 📧 关注邮件/GitHub通知
  • 💬 回应评论
  • 🔧 根据反馈修改代码

如何修改PR：

# 在同一分支继续修改
git add .
git commit -m "fix: 根据review修改"
git push

# PR会自动更新

📝 贡献文档

文档同样重要！

文档位置

  • Wiki: docs/wiki/
  • README: README.md

改进文档

  1. Fork项目（同代码贡献）
  2. 编辑markdown文件
  3. 提交PR

文档编写规范：

  • 🎯 简洁明了
  • 📖 分段清晰
  • 💡 提供示例
  • 🎨 使用emoji增强可读性（但不要过度）
  • 📸 必要时添加截图

示例：

## 配置API Key

按以下步骤配置：

1. **获取API Key**
   访问 [Google AI Studio](https://makersuite.google.com/app/apikey)

2. **填写配置**
   ```env
   VITE_LLM_API_KEY=你的KEY
   ```

3. **验证**
   重启应用，尝试分析一段代码

💡 **提示**：首次使用建议选择Gemini，免费额度大

⭐ 其他贡献方式

推广项目

  • 在社交媒体分享
  • 写博客介绍使用体验
  • 在技术社区推荐
  • 录制教程视频

回答问题

  • 在Issues中帮助其他用户
  • 在讨论区分享经验
  • 回答Stack Overflow上的相关问题

翻译

  • 翻译文档到其他语言
  • 改进现有翻译

📋 行为准则

我们的承诺

为了营造开放和友好的环境，我们承诺：

  • 🤝 尊重不同的观点和经验
  • 💬 友好地接受建设性批评
  • 🌍 关注对社区最有利的事情
  • ❤️ 对他人表示同理心

不可接受的行为

  • ❌ 使用性化的语言或图像
  • ❌ 人身攻击
  • ❌ 公开或私下的骚扰
  • ❌ 未经许可发布他人隐私
  • ❌ 其他不道德或不专业的行为

🎯 代码质量要求

提交前检查清单

  • 代码通过 pnpm lint
  • 类型检查通过 pnpm type-check
  • 能成功构建 pnpm build
  • 在浏览器中测试过
  • 没有console.log等调试代码
  • 提交信息符合规范
  • 更新了相关文档

性能考虑

  • ⚡ 避免不必要的re-render
  • 🎣 合理使用React Hooks
  • 📦 组件懒加载（大组件）
  • 🖼️ 图片优化

可访问性

  • ♿ 使用语义化HTML
  • 🔘 可键盘导航
  • 🎨 足够的颜色对比度
  • 📝 提供alt文本

🏆 贡献者

感谢所有贡献者！你的名字会出现在：

  • README的贡献者列表
  • 项目网站（计划中）
  • Release Notes

❓ 常见问题

Q: 我是新手，能贡献吗？

当然！ 我们欢迎所有水平的贡献者。

建议：

  • 从小改动开始（如文档）
  • 选择标记为 good first issue 的Issue
  • 不懂就问，维护者会帮助你

Q: 我的PR多久会被审查？

通常：

  • 小改动：1-3天
  • 大改动：1周内

如果超过1周没响应：

  • 礼貌地在PR下评论提醒
  • 或发邮件给维护者

Q: PR被拒绝了怎么办？

不要灰心！ 常见原因：

  • 与项目方向不符
  • 需要更多讨论
  • 已有类似PR

建议：

  • 先在Issue中讨论
  • 询问维护者意见
  • 小步迭代，多次PR

Q: 如何保持Fork同步？

# 拉取上游更新
git fetch upstream

# 合并到主分支
git checkout main
git merge upstream/main

# 推送到你的Fork
git push origin main

📞 联系方式

有疑问？

❤️ 再次感谢你的贡献！

每一个PR，每一个Issue，每一个Star

都是对开源项目最大的支持

🚀 Let's make XCodeReviewer better together!

📚 文档导航

🚀 新手入门

📖 使用教程

👨‍💻 开发相关

⭐ 喜欢这个项目？

给个Star吧

Clone this wiki locally