AtomGit 新手教程：Issue 和 PR 是什么？从 Fork、Clone 到提交 Pull Request 全流程

AtomGit 新手教程：Issue 和 PR 是什么？从 Fork、Clone 到提交 Pull Request 全流程

本文面向刚接触 Git、AtomGit 和开源协作的同学，介绍 Issue、PR、Fork、Clone、Commit、Push 的区别，并完整演示如何提交一个 Issue 和 Pull Request。

示例项目：

https://atomgit.com/XJ-Cyber/text-one

这是一个测试项目，可以用来练习提交 Issue 和 PR。

一、Issue 和 PR 分别是什么？

1. Issue：用于记录和跟踪问题

Issue 可以翻译为"议题"或"问题单"。在代码托管平台中，它是一条可以持续讨论和跟踪的项目记录。

Issue 常见用途包括：

报告 Bug；
询问项目的使用方法；
提出新功能建议；
记录文档改进项；
拆分和跟踪开发任务。

因此，Issue 不只是"提问"。它也可以是一条需求、一项任务或一个 Bug 报告。

2. PR：请求项目合并自己的修改

PR 是 Pull Request 的缩写，通常译为"拉取请求"或"合并请求"。

提交 PR 的含义是：

我已经完成了一组代码或文档修改，请项目维护者审查这些修改，并决定是否合并到目标分支。

PR 中通常包含：

修改了哪些文件；
每一行具体发生了什么变化；
为什么要进行这些修改；
相关人员的审查意见；
自动测试或人工检查结果。

提交 PR 后，项目维护者可以同意、评论、要求继续修改或拒绝。只有 PR 被正式合并后，修改才会进入原项目。

3. Issue 与 PR 的区别

对比项	Issue	PR
核心作用	记录问题、建议或任务	请求审查并合并修改
是否必须修改文件	否	是
主要内容	问题描述和讨论	代码或文档差异、提交记录和讨论
最终状态	关闭	合并或关闭
两者关系	可以被 PR 解决	可以关联对应的 Issue

Issue 和 PR 不要求同时存在。简单的错别字可以修改后直接提交 PR；复杂问题则适合先提 Issue，讨论清楚后再提交 PR。

如果一个 PR 用于解决 Issue #12，可以在 PR 描述中写：

text 复制代码

Closes #12

平台支持自动关联时，PR 合并后，对应 Issue 会自动关闭。

二、Fork、Clone、Commit 和 Push 的区别

新手提交 PR 时，最容易在下面几个概念之间混淆。

名称	发生位置	作用
Fork	AtomGit 网站	将原仓库复制到自己的账号下
Clone	本地电脑	将远程仓库下载到本地文件夹
Commit	本地 Git 仓库	保存一次带说明的版本记录
Push	本地到远程	将本地提交上传到远程仓库
PR	AtomGit 网站	请求原项目合并自己的修改

需要特别注意：

Fork 得到的是自己账号下的远程仓库；Clone 得到的是电脑里的本地仓库。

完整流程如下：

text 复制代码

原项目
  ↓ Fork
个人账号下的仓库
  ↓ Clone
电脑中的本地仓库
  ↓ 修改、Commit、Push
个人账号下的仓库
  ↓ 提交 PR
原项目审查并合并

三、AtomGit 提交 PR 的完整步骤

步骤 1：Fork 原项目

打开原项目页面，点击 Fork。

选择自己的个人空间，确认创建 Fork。

操作完成后，自己的账号下会出现一份同名仓库。

Fork 后的仓库归自己管理，可以在其中创建分支和推送修改，但它不是原仓库本身。

步骤 2：同步源项目

如果原仓库已经有了新的提交，建议在开始修改前先同步。

在个人 Fork 的页面中点击"同步源项目"，将原仓库的最新修改同步过来。

同步可以降低代码冲突的概率，但不能保证一定没有冲突。多人同时修改同一文件的相同位置时，仍然可能需要手动处理冲突。

步骤 3：Clone 个人 Fork 到本地

进入自己的 Fork 仓库，复制克隆地址。

打开终端，进入准备保存项目的目录：

bash 复制代码

cd ~/Desktop
git clone <你的 Fork 仓库地址>
cd text-one

例如：

bash 复制代码

git clone https://atomgit.com/你的用户名/text-one.git

请将示例地址替换为自己的真实仓库地址。

步骤 4：创建独立分支

推荐为每一项修改创建一个单独分支：

bash 复制代码

git switch -c docs/issue-pr-guide

分支名应尽量表达修改目的，常见示例：

text 复制代码

docs/update-readme
fix/login-button
feature/dark-mode

如果本机 Git 版本较旧，不支持 git switch，可以使用：

bash 复制代码

git checkout -b docs/issue-pr-guide

步骤 5：修改并检查文件

使用编辑器打开项目，完成代码或文档修改。本示例新增了 Issue和PR说明.txt。

先查看当前修改：

bash 复制代码

git status
git diff

确认修改内容正确后，再执行提交命令。

步骤 6：Commit 并 Push

执行以下命令：

bash 复制代码

git add -- 'Issue和PR说明.txt'
git diff --cached --check
git commit -m "docs: add Issue and PR explanation"
git push -u origin docs/issue-pr-guide

各命令的作用如下：

命令	说明
`git add -- 'Issue和PR说明.txt'`	将指定文件加入暂存区
`git diff --cached --check`	检查暂存内容中的空白符等格式问题
`git commit -m "..."`	创建本地提交并填写提交说明
`git push -u origin ...`	将当前分支首次推送到个人远程仓库

原示例直接执行 git push origin main 也可以把个人 Fork 的 main 推送到远程，但不建议长期这样操作。使用独立分支可以让不同任务互不干扰，PR 的修改范围也更清晰。

推送完成后，个人仓库中可以看到新增或修改的文件。

步骤 7：创建 Pull Request

进入 PR 页面，选择创建新的 PR。

选择分支时重点检查：

text 复制代码

源仓库：自己的 Fork 仓库
源分支：docs/issue-pr-guide
目标仓库：原项目仓库
目标分支：main

源和目标选反，会导致 PR 方向错误。确认后点击下一步。

步骤 8：填写 PR 描述

PR 标题应简洁说明修改内容，例如：

text 复制代码

docs: 新增 Issue 和 PR 入门说明

正文可以使用下面的模板：

markdown 复制代码

## 修改内容

新增 Issue 和 PR 的入门说明文档。

## 修改原因

帮助第一次参与项目协作的同学理解基本流程。

## 验证方式

- 已检查文档内容
- 已检查排版和文件名

## 关联 Issue

Closes #12

没有对应 Issue 时，可以删除"关联 Issue"部分，直接提交 PR。

步骤 9：等待审查和合并

创建成功后，PR 会进入待审查状态。

维护者可以查看文件差异、提交记录和讨论内容。如果维护者要求修改，不需要关闭 PR。继续在原分支修改并执行 commit、push，新的提交通常会自动出现在同一个 PR 中。

项目所有者或拥有权限的维护者可以执行合并。

显示"已合并"，代表修改已经进入原项目。

返回原仓库，可以看到合并后的文件。

四、AtomGit 提交 Issue 的完整步骤

步骤 1：进入原项目的 Issue 页面

与原项目有关的问题，一般应提交到原项目，而不是自己的 Fork 仓库。

步骤 2：填写 Issue

点击新建 Issue，填写标题和正文。标题需要准确概括问题。

不推荐的标题：

text 复制代码

运行不了
项目报错
求帮助

推荐的标题：

text 复制代码

Windows 11 下执行 npm install 时提示 EACCES
README 中缺少 Python 版本要求
建议增加深色模式

Bug 类 Issue 可以使用下面的模板：

markdown 复制代码

## 问题描述

简要说明遇到的问题。

## 复现步骤

1. 执行了什么操作
2. 输入了什么命令
3. 在哪一步出现问题

## 实际结果

粘贴完整报错信息或添加截图。

## 预期结果

说明正常情况下应该发生什么。

## 运行环境

- 操作系统：Windows 11
- 软件版本：Node.js 22.x
- 项目版本或提交：main / commit id

标签可以帮助维护者分类，但通常不是必填项。不确定选什么时，可以先不添加。

步骤 3：提交并继续跟进

提交完成后，Issue 会出现在问题列表中。

后续需要关注维护者的回复。如果对方要求补充日志、版本号或复现步骤，应尽量在原 Issue 中继续回复，避免重复创建多个相同问题。

五、常见问题

1. 提交 PR 前必须先提 Issue 吗？

不必须。复杂修改适合先提 Issue 讨论；简单、明确的修复可以直接提交 PR。具体以项目的贡献指南为准。

2. PR 提交后还能继续修改吗？

可以。在创建 PR 的源分支中继续提交并 Push，新的提交会更新到原 PR 中。

3. 为什么我没有合并按钮？

普通贡献者通常没有向原项目执行合并的权限。合并操作由项目所有者或维护者完成。

4. 如何减少代码冲突？

修改前同步原项目；一个分支只处理一项任务；尽量避免无关格式化；不要在一个 PR 中混入多个不相关功能。

5. Issue 提交后没人回复怎么办？

先检查问题描述是否完整，也要考虑维护者可能没有及时处理。可以在合理时间后补充一次信息，但不要频繁重复催促或创建相同 Issue。

六、流程总结

提交 PR 的标准流程：

text 复制代码

Fork → 同步源项目 → Clone → 创建分支 → 修改文件
→ git add → git commit → git push → 创建 PR → 审查 → 合并

提交 Issue 的标准流程：

text 复制代码

进入原项目 → 打开 Issue 页面 → 填写标题和正文
→ 提交 → 补充信息和参与讨论 → 问题解决后关闭

对于第一次练习的同学，建议先完成两个小任务：提交一个描述清楚的 Issue，再修改一个错别字并提交 PR。完整操作一次后，这些概念会比单独背定义更容易理解。

推荐标签： Git、AtomGit、Pull Request、Issue、开源、Git教程