GitHub开源项目贡献：PR工作流与最佳实践 (Version 2024.07.28)

Roxi 加速器 — 稳定·快速·安全

全球节点覆盖，支持所有主流平台，一键连接无需配置。新用户免费试用。

立即体验 →

Version: 2024.07.28

1. 前置条件与环境配置

在发起任何代码贡献之前，确保本地开发环境已正确配置。

1.1 软件依赖

• Git 2.30.0 或更高版本。
• GitHub账户。
• SSH密钥配置（推荐）。

1.2 Git配置

配置Git用户信息，确保提交记录可追溯。

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Expected Output: (No direct output, configuration saved.)

Note: 使用与GitHub账户关联的邮箱地址。

2. PR工作流：Fork, Clone, Branch, Commit, Push, PR

标准的GitHub PR工作流遵循以下步骤。此流程旨在最小化对主仓库的直接修改，并通过审查机制保障代码质量。

2.1 Fork主仓库

通过GitHub网页界面，将目标开源项目Fork到个人账户下。这将创建一个可独立操作的副本。

2.2 Clone个人Forked仓库

将个人Forked仓库克隆到本地开发环境。

git clone [email protected]:YourGitHubUsername/repository-name.git
cd repository-name

Expected Output:

Cloning into 'repository-name'...
remote: Enumerating objects: XX, done.
remote: Counting objects: 100% (XX/XX), done.
... (repository content download progress)
Resolving deltas: 100% (YY/YY), done.

2.3 添加上游(upstream)远程仓库

配置上游仓库，以便同步主项目的最新变更。

git remote add upstream [email protected]:OriginalOwner/repository-name.git

Expected Output: (No direct output)

验证远程仓库配置：

git remote -v

Expected Output:

origin  [email protected]:YourGitHubUsername/repository-name.git (fetch)
origin  [email protected]:YourGitHubUsername/repository-name.git (push)
upstream  [email protected]:OriginalOwner/repository-name.git (fetch)
upstream  [email protected]:OriginalOwner/repository-name.git (push)

2.4 同步最新主分支代码

在开始新功能开发或Bug修复前，务必同步主仓库的最新代码，避免合并冲突。

git checkout main
git pull upstream main

Expected Output:

From github.com:OriginalOwner/repository-name
 * branch            main       -> FETCH_HEAD
Already up to date.

2.5 创建功能分支

基于最新main分支创建独立的功能分支。分支命名应清晰表达其用途，例如 feature/add-new-api 或 bugfix/fix-login-issue。

git checkout -b feature/your-feature-name

Expected Output:

Switched to a new branch 'feature/your-feature-name'

2.6 编码与提交

在功能分支上进行代码修改。提交(commit)频率应高，每次提交应完成一个逻辑上的最小变更单元。提交信息(commit message)应遵循项目约定，通常为<type>: <subject>格式。

示例：

git add .
git commit -m "feat: implement user authentication module"

Expected Output:

[feature/your-feature-name XXXXXXX] feat: implement user authentication module
 X files changed, Y insertions(+), Z deletions(-)

Warning: 避免在一次提交中混合不相关的变更。提交信息是代码历史的重要组成部分，应力求清晰、简洁。

2.7 推送功能分支到个人Forked仓库

将本地功能分支推送到个人GitHub Forked仓库。

git push origin feature/your-feature-name

Expected Output:

Enumerating objects: XX, done.
Counting objects: 100% (YY/YY), done.
... (upload progress)
remote: Create a pull request for 'feature/your-feature-name' on GitHub by visiting:
remote:   https://github.com/YourGitHubUsername/repository-name/pull/new/feature/your-feature-name
... (push details)

2.8 创建Pull Request (PR)

访问个人Forked仓库的GitHub页面，通常会提示创建PR。确保PR的目标分支是主仓库的main分支（或项目指定的贡献分支）。PR标题应简洁明了，PR描述应详细说明本次变更的目的、解决了什么问题、如何实现以及任何相关的测试信息。

Note: 遵循项目提供的PR模板（如果存在）。

3. PR审查与迭代

PR创建后，项目维护者会进行代码审查。根据审查意见，可能需要进行代码修改和再次提交。

3.1 根据审查意见修改代码

在本地功能分支上进行修改。

# Make changes...
git add .
git commit -m "fix: address reviewer comments on X"

Expected Output: (Similar to 2.6 commit output)

3.2 推送更新到PR

修改后的代码直接推送到原功能分支，PR会自动更新。

git push origin feature/your-feature-name

Expected Output: (Similar to 2.7 push output)

Note: 避免创建新的PR，直接在现有PR上迭代。

3.3 合并PR

当PR通过所有审查和CI/CD检查后，项目维护者会将其合并到主仓库。在此之后，本地功能分支和个人Forked仓库的功能分支可以删除。

4. 最佳实践与注意事项

• 频繁同步上游： 每次开始新任务前，首先从上游main分支拉取最新代码。
• 原子性提交： 每次提交只包含一个逻辑变更，便于代码审查和回溯。
• 清晰的提交信息： 遵循 Conventional Commits 规范（如果项目采用）。
• 本地测试： 提交PR前，确保所有本地测试通过。
• 文档更新： 如果代码变更影响了功能或接口，请同步更新相关文档。
• 遵循项目规范： 仔细阅读项目的CONTRIBUTING.md文件，了解其特有的贡献指南和代码风格。
• GitHub镜像站： 如果遇到 GitHub打不开怎么办 或下载慢的问题，可以尝试使用 GitHub加速下载 提供的镜像站服务。

此流程旨在确保代码贡献的效率与质量，降低集成风险。严格遵循这些步骤将有助于项目维护者更快地审查和合并您的贡献。

References

• About pull requests - GitHub Docs
• Conventional Commits v1.0.0