跳到主要内容

项目贡献指南

欢迎为公司项目贡献代码！本指南将帮助你了解如何参与项目开发，从环境准备到提交 Pull Request 的完整流程。

前置准备​

1. 注册 GitHub 账号并加入组织​

  1. 如果你还没有 GitHub 账号，请先访问 GitHub 注册一个账号
  2. 将你的 GitHub 用户名提供给管理员
  3. 等待管理员将你添加到 beisi-tech 组织
  4. 查收邮件并接受组织邀请，成为组织成员

2. 安装 Git 工具​

推荐使用 GitHub Desktop（图形化界面，操作更方便）：

  1. 访问 GitHub Desktop 官网 下载安装
  2. 安装后登录你的 GitHub 账号
  3. GitHub Desktop 会自动配置 Git 环境

或者使用命令行 Git：

  1. 访问 Git 官网 下载安装
  2. 安装后通过以下命令验证：
git --version

开发流程​

分支说明​

  • main：稳定发布分支
  • dev：日常开发分支，PR 合并目标
  • feature/*、fix/*：功能/修复分支，从 dev 切出

第一步：Fork 仓库​

统一使用 Fork + PR 流程，即使你有写权限也不要直接推送到 main/dev。

  1. 打开项目的 GitHub 页面
  2. 点击右上角 Fork，将仓库 Fork 到你的账号下

第二步：克隆到本地并绑定 upstream​

使用 GitHub Desktop（推荐）：

  1. 打开 GitHub Desktop
  2. 点击 File → Clone repository
  3. 在 GitHub.com 标签下找到你 Fork 的仓库
  4. 选择本地保存路径，点击 Clone

使用命令行：

git clone https://github.com/你的用户名/仓库名.git
cd 仓库名
git remote add upstream https://github.com/beisi-tech/仓库名.git

第三步：同步 dev 分支​

在开始工作前，先同步 dev 分支：

git fetch upstream
git checkout dev
git pull upstream dev

如果本地没有 dev 分支，先创建：

git checkout -b dev upstream/dev

第四步：从 dev 切出功能分支​

git checkout -b feature/your-feature

第五步：本地开发与格式化​

  1. 在本地完成需求开发
  2. 遵循项目规范文档：
  3. 本地不要求运行 linter，使用 Prettier 进行格式化（参考 Prettier 教程）
  4. 默认不要求编写单元/集成测试，除非负责人特别要求

第六步：提交代码​

使用 GitHub Desktop（推荐）：

  1. GitHub Desktop 会自动显示你修改的文件
  2. 在左下角的 Summary 填写提交说明（遵循 Conventional Commits）
  3. 点击 Commit to feature/xxx 提交

使用命令行：

git status
git add .
git commit -m "feat: 添加新功能描述"

重要提示： 如果你的提交是为了关闭某个 Issue，在 commit 信息末尾添加 fix: #issue编号，例如：

git commit -m "fix: 修复登录按钮样式问题 fix: #123"

第七步：推送到你的远程仓库​

git push origin feature/your-feature

第八步：创建 Pull Request​

  1. 进入你 Fork 的仓库页面，点击 Compare & pull request
  2. 确认 base 为 beisi-tech/仓库名:dev，compare 为你的 feature/xxx
  3. PR 描述中说明：
    • 本次改动做了什么
    • 为什么这样做
    • 可能的影响或风险
    • 相关 Issue（Closes #issue编号 或 Fix #issue编号）
  4. 点击 Create pull request 提交

注意：GitHub Desktop 不支持直接创建 PR，必须在网页上操作。

第九步：代码审核与合并​

  1. PR 会先由自动化 bot 执行检查
  2. 负责人进行最终审查
  3. 审查通过后合并到 dev

PR 修改流程​

如果第一次提交的 PR 没有被批准，需要修改代码，按以下步骤操作：

不要创建新的 PR！ 直接在原来的分支上继续修改：

使用 GitHub Desktop（推荐）：

  1. 根据审核意见修改代码
  2. 在 GitHub Desktop 中提交修改（填写 commit 信息）
  3. 点击 Push origin 推送
  4. 原来的 PR 会自动更新

使用命令行：

# 修改代码...

# 提交修改
git add .
git commit -m "fix: 根据审核意见修改xxx"

# 推送到远程（会自动更新原 PR）
git push origin feature/your-feature

推送后，原来的 Pull Request 会自动更新，管理员会看到你的新提交。

注意事项​

推荐做法​

  • 每个 PR 只解决一个问题，保持改动最小化
  • 提交前先在本地测试，确保代码可以正常运行
  • 遵循项目的代码规范和 Commit 规范
  • 及时同步主仓库的最新代码，避免冲突
  • PR 描述清晰，说明改动原因和实现方式

避免做法​

  • 不要在一个 PR 中包含多个不相关的改动
  • 不要提交无意义的 commit 信息（如 "update"、"修改"、"fix" 等）
  • 不要在 PR 被拒绝后创建新的 PR，应在原 PR 上继续提交
  • 提交前务必先拉取最新代码，避免冲突
  • 不要直接推送或 force push 到 main/dev

关联 Issue​

在提交代码时，可以通过以下关键词自动关闭 Issue：

  • fix: #123 或 fixes: #123 或 fixed: #123
  • close: #123 或 closes: #123 或 closed: #123
  • resolve: #123 或 resolves: #123 或 resolved: #123

示例：

git commit -m "fix: 修复登录页面样式错误 fix: #456"

当这个 commit 所在的 PR 被合并后，Issue #456 会自动关闭。

获取帮助​

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

  1. 查看项目的 规范文档
  2. 在对应的 Issue 下留言询问
  3. 联系项目维护人员

感谢你的贡献！