【HelloKitty团队项目】代码管理

[HelloKittyTeam]

项目	内容
这个作业属于哪个课程	2023北航软件工程
这个作业的要求在哪里	团队项目-代码管理准备
我在这个课程的目标是	学习软件工程技术，完成团队开发流程
这个作业在哪个具体方面帮助我实现目标	熟悉代码管理，制定开发规范

目录

• 基本说明
• 问题记录与解决方案
• merge 与 rebase操作
• 结合分支图对代码管理的建议
• 代码管理风险与应对

基本说明

• 团队的代码仓库地址 (PRO版)：https://github.com/Mmmusel/BUAASE2023-HelloKitty-TVC-PRO

• 团队完成 Task. HotFix! 后新建的代码仓库地址：https://github.com/Mmmusel/BUAASE2023-HelloKitty-TVC-HotFix

• 需要说明的情况：

由于第一次完成代码管理作业时，我们犯了很多忽略了 Git 规范的错误，包括但不限于：在发起 pr 时merge，没有在本地开发时 rebase 到最新 dev 分支后再提交，导致分支树混乱，commit 历史之间存在大量重复内容；进行 fix 时，没有引用 issue，或者没有将 issue 随 pr 自动关闭；commit message没有统一等问题。所以我们将第一次的代码管理作业命名为 DRAFT版，仓库链接如下及分支图如下：

【DRAFT版】https://github.com/Mmmusel/BUAASE2023-HelloKitty-TVC-DRAFT

第一次作业完成后，团队成员反思总结了第一次作业中产生的问题，并第二次依照 Git 规范完成代码管理作业的PRO版，仓库链接如下及分支图如下：

【PRO版】https://github.com/Mmmusel/BUAASE2023-HelloKitty-TVC-PRO

在HotFix删除敏感信息文件中，我们使用bfg工具：

• 新建仓库，并从原有仓库克隆

• 将仓库克隆到本地，拉取所有远程分支到本地

  git clone xxx
  git fetch --all
  for b in `git branch -r | grep -v -- '->'`; do git branch --track ${b##origin/} $b; done
  

• 删除所有路径下的SUPER-SENSITIVE-DATA.txt文件，推送到远程仓库

  bfg --delete-files *SUPER-SENSITIVE-DATA.txt
  git reflog expire --expire=now --all && git gc --prune=now --aggressive
  git push-f --all
  

问题记录与解决方案

• fix分支没有关联issue；issue不能在pull request时自动关闭

  • 在实际的开发规范中，issues的关闭应该分为以下两种情况：

    • issue在开发中被解决，此时issues应当在创建pr时的 comment 中使用close #1的形式关联并自动关闭。
    • issue尚未被解决并且关停此issue，此时才应当在issue界面手动close。

  • 问题描述：在第一次尝试中，我们在 fix->dev 的pr中使用close #1仍然无法自动关闭 issue。

  • 解决方法：经过查询github官方文档，发现此随pr自动关闭issue的机制只适用于向 default 分支发起的 pr，所以由仓库创建者在Settings -> Branches -> Default Branch 中修改默认分支为dev即可。具体说明在此处 Github Docs: Linking a pull request to an issue

• 创建issue时不能选择模板

  • 产生原因：在第一次的尝试中在非default分支的dev分支下配置了模板，导致模板无法使用。
  • 解决办法：配置的issues只有在远端default分支下存在，才能在 issues 界面看到并引用此模板。

• feature/fix分支的功能最小化

  • 问题描述：第一次作业尝试中，成员在一个feature/fix分支上多次发起pr，导致一个分支用于解决多项问题，也带来更多代码冲突的风险，不利于管理

  • 在实际开发时，仓库管理者应当提前设置好pr被并入后删除分支，需要防止成员在一个feature/fix分支上多次发起pr，导致一个分支用于解决多项问题，不利于管理。

  • 在第二次尝试中，设置了向dev分支发起的pr被合并时，自动删除被并入分支。由于一开始没有注意本次作业要求保留所有分支，所以分支自动删除后在pr页面也可以手动 restore branch。

• main及release分支的提交信息出现多余commit history

  • 问题描述：dev->release及release->main时，不应该在release及main分支上使用squash、merge等命令，而应该尽量使用rebase，否则会出现一次的merge中包含dev分支上所有commit的情况

• 在最初尝试中，分支名以及commit信息不统一

  • 解决方法：及时通过文档来制定统一的规范，确保小组成员彼此能够顺利高效地理解彼此的修改与提交。

• 不熟悉开启pull request的步骤，导致检出的分支rebase到main分支上。

  • 解决：

    git reflog # 找到rebase操作的提交哈希值
    git reset --hard <commit-hash> # 回滚
    git push -f origin my-branch # 强制push到远端并覆盖(注意和组员沟通)
    

  • 避免：

    进行rebase前留意合并到哪个分支上。

• 在github上pull request时无法rebase and merge

  • 产生原因：

    • 没有拉取dev分支导致rebase后push到远端仓库时，需要额外进行merge。

    • 未正确进行rebase。当push到远程仓库的新分支xxx和主分支dev存在冲突时，github会在pull request阶段要求解决冲突，如果此时在github中解决冲突，会直接将dev分支merge到xxx分支上，因此无法再将xxx分支rebase到dev上。导致提交树出现如下的结果。虽然最后dev分支的代码是符合预期的，但由于存在大量的merge信息，这样的提交树非常混乱，难以对过往版本进行追踪。

    

  • 解决：如果想彻底删除该记录，可以删除本地commit记录，再强制push到远端仓库，但注意这个过程要先与组员沟通好，避免提交混乱。

  • 避免：push前先将本地dev分支与远端同步，然后将本地新建分支rebase为最新的dev分支。具体pull request流程如下：

    1. 开发初期检出时，dev分支处于完成 TASK1 的版本

       git checkout my-branch origin/dev
       # 或者使用 git reset --hard TASK1的commit_id 来模拟基于早期TASK1版本的检出
       

    2. 完成本地修改

       git add .
       git commit -m "[feat](TASK2-2): xxx"
       

    3. 更新本地dev分支为最新版本

       git checkout dev
       git pull origin dev        # 同步dev分支
       

    4. 将本地新建分支rebase为最新的dev分支

       git checkout my-branch
       git rebase origin/dev    # 将检出分支rebase到dev分支
       # 处理冲突
       ## 此时会进入一个用于处理冲突的分支
       git rebase --continue    # 首先查看当前待解决的冲突文件
       ## 逐一手动合并冲突文件
       git add filename        # 提交修改                
       git rebase --continue    # 当所有冲突文件解决完毕后，使用此指令进入commit message编辑
       # 保存并退出commit message编辑，冲突解决完毕，回到原分支
       

    5. 进行后续开发或者发起pr

  • 根据该规范进行操作后，dev分支的提交树如下。可以看到此时的提交树不再包含merge信息，所有人的提交都被完全合并到了dev分支里，看起来就像是所有人都用dev分支进行开发一样。

    

• 意外引入的.DS_Store文件导致多处pr出现冲突需要merge

  • 问题描述：第二次代码管理作业中，唯一一处使用了merge的地方是一位同学将MacOS自带的.DS_Store文件提交到仓库，导致向dev分支以及release分支合并pr时均无法rebase and merge，需要解决冲突。
  • 解决方案：保证.gitignore文件的覆盖性，增加对.DS_Store文件的限制。

merge 与 rebase操作

git merge和git rebase都是用于合并不同分支的更改的工具，但它们采用不同的策略来合并更改，区别主要在于得到的提交树不同。

git merge是将多个分支的更改集成到一起，生成一个新的合并提交。合并提交包括多个分支的历史记录，并且会新建一个merge提交记录，冲突记录保存在新建的merge提交记录中。通常会保留每个分支的历史记录，并将它们合并到一个新的提交中。在分支图中，检出子分支后主分支的提交和子分支的提交呈并行结构。

• git merge 使用场景：当子分支开发完成后，需要将子分支重新合并到主分支上，此时使用merge完成合并。

git rebase相当于在最新的主分支上重新创建了一个子分支，然后把原来的子分支中所有提交复制到这个新的子分支上。这种方式可以保持提交历史的线性，处理冲突的记录保存在子分支的某些提交中，不会新建提交节点，看起来更加干净和整洁，但是也可能会丢失一些提交的信息。

• git rebase 使用场景：开发某一模块时，和该模块有逻辑关联的其他模块在主分支上发生了更新，因此本地的子分支也需要同步完成这些更新。

在实际使用中，如果想保留每个分支的独立历史记录，以及它们之间的分支点，那么就应该使用git merge。如果想保持提交历史的线性，并且不介意删除一些提交的信息，那么就应该使用git rebase。

结合分支图对代码管理的建议

虽然第二次作业使用rebase将分支树整合成线性结构，但这样的提交树由于将所有人的分支都完全整合到了dev分支上，所以如果想看开发某模块的分支中的提交记录时不是很方便。因此最终团队更倾向于用下面这样的提交方式。

1. 本地代码使用rebase实现子分支对主分支的同步（即与上述pull request的1-4流程相同）。
2. push后，在pull request阶段使用merge request完成子分支到主分支的合并（而不是rebase and merge）。

这样操作后的提交树会变成如下形式：

其中黄色的为dev分支，紫色为子分支。这样的提交树可以很方便的看到每个人新建的子分支提交流程，相较于全部整合到主分支上的更加清晰，且没有多余的merge信息。

代码管理风险与应对

1. 版本控制错误：在代码管理中，版本控制是一个非常重要的方面。错误的版本控制可能导致代码丢失、覆盖或出现其他不可预测的问题。为了避免这种风险，团队需要定期备份代码，并且每个开发人员都应该了解如何正确地使用版本控制工具。此外，仓库管理员应该在开发初期就设置好各成员的仓库权限，防止意外操作导致版本丢失。

2. 同步问题：在团队协作中，可能会出现多人同时修改同一代码文件的情况，此时在代码同步合并时会发成冲突，容易在合并同步时出现错误。为避免此类问题，我们团队约定了 Pull Request 的流程和处理规则，以确保团队协作的有序性和高效性，具体包括：团队成员应该尽量缩小每次feature/fix分支的粒度，将分支代码修改最小化，避免和其他成员发成大量冲突。同时，也应当在每次开发前与发起pr前都拉取dev分支并使用rebase在本地解决好冲突。

3. 代码和提交信息不规范问题：在团队协作中，多人合作完成同一项任务时，大家提交的代码和说明信息都需要能够很容易地彼此理解彼此地修改或实现的内容，否则不利于合作开发的顺利推进影响沟通效率。为了提高代码可读性以及实现功能的易理解性，需要制定统一易理解代码规范注释规范和commit信息、分支命名、提issue时的信息填写等版本控制的规范。适用于我们团队的版本管理系统协作规范包括：

   • 使用具体的提交信息，包括提交类型、所涉及的文件和修改内容等，以便快速理解代码修改的目的和影响；
   • 约定统一的分支命名规则，如：<type>(<scope>): <subject> <body>，以方便团队成员理解分支的含义。

4. 对于代码风险管理，可以采用这样的分支管理方式：

   Feature: 单一功能的开发, 测试分支, 对代码等级要求较低.

   Fix: 单一Bug的修复, 测试分支, 对代码等级要求较低.

   Dev: 开发团队用以合并功能的分支, 对代码的最低要求为可开发, 可复现, 可检验.

   Release: 用以交付的分支, 对代码的最低要求为可开发, 可复现, 可检验, 可回滚.

   Hotfix: Release的一种特殊类型, 常见于对旧系统的临时性修复, 但是其代码需要向dev和master进行合并.