项目 GitHub Flow 流程

FAA-web和FAA本体采用同样的工作流程, 阅读本文有助于您参与该工作流进行开发工作, 为您和开发组带来便捷的体验.

团队希望维护一个干净、可部署的主分支(main). 因此云端主分支应用分支保护, 必须通过PR进行代码审查和合并.

Git 基本原理

如果您是一位初学者, 完全没有了解过版本控制工具, 请详细阅读本章节. 如果实在不想读也没关系, 直接实操一下回来看看就懂了

Git是一个分布式版本控制系统，用于跟踪代码的更改，并允许多个开发者同时工作. 它的运行如下图所示. 通过将用户工作区 / 本地仓库 / 远程仓库 分别储存, 并保留期间的历史记录, 让开发者可以轻松地跟踪更改，并轻松地恢复到任何版本。

在使用前, 您需要自行搜索下载该软件, 它的部署没有任何特殊要求，就像普通的软件下载和安装一样. 注意：软件名称就叫做Git而非Gtihub, 这是两个不同概念.

alt text

为方便初学者理解, 我们对这些名词进行解释.

基本概念

• 分支: 表示软件开发的不同历史路径，由一系列的提交组成，每个分支代表一个独立的开发线程。
• 提交: 代表代码的一个版本，可以视为代码在某一时刻的完整快照，记录了文件的变更和元数据。

层级结构

• 工作区(Working Directory): 存储在您的硬盘上的项目目录，这里是您日常编辑代码的地方。
• 暂存区(Staging Area): 位于工作区和本地仓库之间，用于收集和准备即将提交的改动，允许您精细化管理每次提交的内容。
• 本地仓库(Local Repository): 存储在本地硬盘上的版本库，包含项目的所有提交历史和分支信息。
• 远程仓库(Remote Repository): 位于网络上的版本库，如GitHub、GitLab等平台上的仓库，用于团队协作和代码共享。

核心指令

• 添加(Add)
  • 将工作区中的文件或改动添加到暂存区，为提交做准备。
  • 支持通过图形界面或命令行逐行或逐文件添加。
• 提交(Commit)
  • 将暂存区的改动正式记录到本地仓库，形成一个新的提交节点。
  • 提交应尽量保持原子性，每次提交最好只包含一个功能点或修复。
  • 编写清晰的提交信息，说明本次提交的目的和改动内容。
• 推送(Push)
  • 将本地仓库的提交同步到远程仓库，使团队成员可以访问最新的代码。
  • 推送时需指定本地分支和远程分支的映射关系，通常推荐使用个人专属的分支。
• 拉取(Pull)
  • Fetch 从远程仓库下载最新的提交信息，但不自动合并到本地仓库。
  • Pull 结合了Fetch和Merge，将远程仓库的改动合并到本地工作区。
• 合并(Merge)
  • 用于合并两个分支的改动，解决冲突后更新本地仓库。
  • 一般情况下，我们推荐使用Merge，而不是Rebase来保留更多细节。
• 变基(Rebase)
  • 重新定位分支，将一系列提交应用到另一个基点上，保持线性的提交历史。
  • 一般用于解决两个开发者从分支的不同节点开始开发导致撞车的问题。
• 签出(Checkout)
  • 切换您的工作区到另一个本地仓库的分支。

流行的开发工具均可使用 可视化界面 操作它们，我们不再需要学习复杂的语法！真棒！

Github Flow 流程

前期准备

• 上游仓库和下游仓库

  • 上游仓库，也就是FAA的主仓库。
  • 下游仓库，也就是通过Fork(类似于复制)FAA主仓库生成的个人仓库。
  • 选择
    • 可以在上游仓库的个人分支直接开发，然后PR到主分支. 对于核心开发者更方便.
    • 可以在下游仓库的主分支直接开发，然后PR到上游仓库的主分支. 无需权限, 自由自在!

• 直接加入开发组 - 在项目主仓库的分支上开发并PR到主分支

  • 加入FAA开发组成为美食大战老鼠高手. 欢迎根据本网页的主页信息联系我们~
  • 在Github中被管理员通过申请，获得主分支以外区域的编辑权限。

• 直接上手开发 - Fork到下游仓库，再PR回上游仓库.

  • 直接在项目Github Fork FAA到您自己的仓库.

• 下载代码

  • 使用clone指令和仓库地址克隆仓库到您本地. 流行的集成开发环境让您可以在可视化界面轻松完成这项工作.
  • 配置好本地仓库和远程仓库的映射关系. 流行的集成开发环境会提示您这么做, 并自动帮您配置映射.
  • 根据.gitignore文件从git上剔除不必要的文件(虽然正常情况下它会自动生效), 包含此类文件的合并请求将不会通过代码审查.

开始开发

确保网络

• 否则会有各种报错超时...

获取主分支更新

• 拉取(Pull)代码在远程仓库最新主分支, 到您的本地仓库, 以更新代码.

更新功能分支

• 初来乍到
  • 既然是初来乍到，代码肯定是最新的~
  • 如果您在FAA主仓库进行开发, 从主分支创建于一个新的分支, 您可以用网名或您要完成的功能为它取名, 标识其独一无二, 强制英文和数字.
• 老熟人
  • 如果您以历史版本为基础进行开发, 请务必先将主分支的最新代码合并到您的功能分支, 确保没有冲突.
  • 如果您Fork了FAA仓库到您自己的储存库开发, 则需要从上游仓库的主分支获取最新代码.
  • 这项工作务必定期进行.

开始写作吧

• 请在完成一个功能模块后, 停笔, 继续下面的流程.
• commit的改动以行为单位, 如果积累太多改动, 将无法分离不同功能, 造成混乱.
• 从一大堆改动中, 逐行勾选对应单个commit的行, 将会极其折磨.

添加(Add)和提交(Commit)到本地仓库

• 遵循原子性 - 一次提交一个功能和改动 的原则，将改动们添加(Add)到暂存区, 再提交(commit)到本地仓库.

推送(Push)本地更改到远程仓库

• 请指定推送(Push)到和您的本地分支同名中.
• 如果远程仓库中没有同名的分支, 将自动新建它.

提交 Pull Request (PR)

• 登录项目Github, 使用可视化界面, 创建新的PR, 选择对比将您的功能分支导入到主分支中.
• 这将触发代码审查机制, 需要其他开发者审阅后才可合并到主分支中.
• 团队成员对PR进行评论和审查后将会通过, 以将您功能分支的改动合并到主分支中, 但期间可能会因为各种原因打回, 此时您需要从头开始这套流程以解决问题.
• 全部完成后, 您可以考虑安全地删除云端仓库上您的功能分支.
• 请遵守PR的原子性规范.
  • 理由
    • 一个PR代表一个功能, 是方便项目管理多人合作的抽象方式.
    • 一个PR将一次性合并两个分支所有不同的commit, 无法选择其中的部分commit. 这也是为什么需要您完成一个功能模块后立刻停笔.
    • 当错误发生时, 为保证主分支的可用性, 会以PR为单位进行分支回退.
  • 不遵守的后果
    • 若将大量互不相关的commit一股脑塞进一个PR中, 发生问题后, 将无法准确回溯故障部分commit, 只能全部回退.
    • 大量不同功能混杂在一起将对进行审查的其他开发者造成极大困扰.
    • 补救措施极其繁琐复杂, 且容易误操作.
  • 补救措施
    • 如果您的分支积累了大量更新却长期未提交, 推荐使用cherry-pick拆分您的commit到临时的提交用分支, 以提交, 并PR, 相关操作在此不展开.
  • 杂项内容
    • 部分极小的杂项commit可以跟着主要改动的PR一起提交. 例如少量改动注释, 格式化, 少量重命名等.