最佳实践

Size: px

Start display at page:

Download "最佳实践"

尽何枪胡
4 years ago
Views:

1 代码托管最佳实践文档版本 04 发布日期华为技术有限公司

2 版权所有华为技术有限公司 2019 保留一切权利非经本公司书面许可, 任何单位和个人不得擅自摘抄复制本文档内容的部分或全部, 并不得以任何形式传播商标声明和其他华为商标均为华为技术有限公司的商标本文档提及的其他所有商标或注册商标, 由各自的所有人拥有注意您购买的产品服务或特性等应受华为公司商业合同和条款的约束, 本文档中描述的全部或部分产品服务或特性可能不在您的购买或使用范围之内除非合同另有约定, 华为公司对本文档内容不做任何明示或默示的声明或保证由于产品版本升级或其他原因, 本文档内容会不定期进行更新除非另有约定, 本文档仅作为使用指导, 本文档中的所有陈述信息和建议不构成任何明示或暗示的担保文档版本 04 ( ) 版权所有华为技术有限公司 i

4 1.1 概述 1.2 CodeHub 云端操作 1.3 Git 本地研发场景 1.4 Git 工作流 1.1 概述文档目的基于 DevCloud 实践所编写, 用于帮助已经掌握或想要掌握 Git 的开发者, 更好的应用 Git, 以及更好的将 Git 与 DevCloud 结合应用 Git 概述集中式版本控制系统从狭义上来说, 版本控制系统是软件项目开发过程中管理代码所有修订版本的软件, 能够存储追踪文件的修改历史, 记录多个版本的开发和维护, 事实上我们可以将任何对项目有帮助的文档交付版本控制系统进行管理版本控制系统 (Version Control Systems) 主要分为两类, 集中式和分布式集中式版本控制系统的特点是只有一台中央服务器, 存放着所有研发数据, 而其它客户端机器上保存的是中央服务器最新版本的文件快照, 不包括项目文件的变更历史所以, 每个相关人员工作开始前, 都需要从这台中央服务器同步最新版本, 才能开始工作, 如下图所示文档版本 04 ( ) 版权所有华为技术有限公司 1

中央服务器在没有备份的情况下, 磁盘一旦被损坏, 将丢失所有数据分布式版本控制系统分布式版本控制系统的特点是每个客户端都是代码仓库的完整镜像, 包括项目文件的变更历史

5 常见的集中式版本控制系统如下图所示集中式版本控制系统的优点与缺点如下表所示表 1-1 集中式版本控制系统描述优点操作简单, 使用没有难度, 可轻松上手文件夹级权限控制, 权限控制粒度小对客户端配置要求不高, 无需存储全套代码缺点网络环境要求高, 相关人员必须联网才能工作中央服务器的单点故障影响全局, 如果服务器宕机, 所有人都无法工作中央服务器在没有备份的情况下, 磁盘一旦被损坏, 将丢失所有数据分布式版本控制系统分布式版本控制系统的特点是每个客户端都是代码仓库的完整镜像, 包括项目文件的变更历史所有数据分布的存储在每个客户端, 不存在中央服务器可能有人会问, 我们公司使用 Git 分布式存储工具, 也有中央服务器啊? 其实, 这个所谓的中央文档版本 04 ( ) 版权所有华为技术有限公司 2

版本库的完整克隆, 包括标签分支版本记录等支持离线提交, 适合跨地域协同开发分支切换快速高效, 创建和销毁分支廉价缺点

6 服务器仅仅是用来方便管理多人协作, 任何一台客户端都可以胜任它的工作, 它和所有客户端没有本质区别, 如下图所示常见的分布式版本控制系统如下图所示分布式版本控制系统的优点与缺点如下表所示表 1-2 分布式版本控制系统描述优点版本库本地化, 版本库的完整克隆, 包括标签分支版本记录等支持离线提交, 适合跨地域协同开发分支切换快速高效, 创建和销毁分支廉价缺点学习成本高, 不容易上手只能针对整个仓库创建分支, 无法根据目录建立层次性的分支文档版本 04 ( ) 版权所有华为技术有限公司 3

7 1.2 CodeHub 云端操作准备工作云端仓库功能华为云账号 Git 客户端已创建好的项目云端仓库功能支持新建仓库仓库克隆分支管理标签管理提交代码拉取代码推送代码代码阅读在线修改仓库成员管理密钥管理等, 更多仓库功能介绍请参见代码托管产品介绍新建空仓库 1. 在 DevCloud 代码托管服务中, 单击上方新建按钮, 选择普通新建如下图所示 2. 配置新仓库的详细信息, 下图所示文档版本 04 ( ) 版权所有华为技术有限公司 4

8 3. 保存仓库信息后, 新建成功的仓库如下图所示设置 SSH 密钥 /HTTPS 密码后续需要在本地客户端进行代码仓库的克隆 / 推送,SSH 密钥和 HTTPS 密码是客户端和服务端交互的凭证, 需要先对它们进行设置设置 SSH 密钥 SSH 密钥是使用 SSH 协议和代码托管服务端交互的凭证, 如果您使用 windows 下的 Git Bash 客户端并在中已经生成, 此步骤可以略过文档版本 04 ( ) 版权所有华为技术有限公司 5

ssh/ id_rsa.pub 的内容打印出来, 如下图所示 cat ~/.ssh/id_rsa.pub b.

9 1. 打开 Git 客户端 (Git Bash 或 linux 的命令行窗口 ), 输入以下命令行 : ssh-keygen -t rsa -C "< 您的邮箱 >" 然后输入 3 个回车 (Enter 键 ) 即可, 生成的 SSH 秘钥对默认在 ~/.ssh/id_rsa ~/.ssh/id_rsa.pub 位置, 如下图所示 2. 添加 SSH 密钥到代码托管服务端 : a. 打开 Git 客户端 (Git Bash 或 linux 的命令行窗口 ), 将 SSH 密钥 ~/.ssh/ id_rsa.pub 的内容打印出来, 如下图所示 cat ~/.ssh/id_rsa.pub b. 复制上述的 SSH 密钥内容, 去到代码托管首页, 单击设置我的 SSH 密钥按钮去到 SSH 密钥管理页面, 单击添加 SSH 密钥进行添加 i. 进入 SSH 密钥管理页面, 如下图所示 ii. 单击添加 SSH 密钥按钮进行添加, 粘贴上述复制的 SSH 密钥内容填写标题, 单击确定即可, 如下图所示文档版本 04 ( ) 版权所有华为技术有限公司 6

10 您已经设置好了 SSH 密钥, 您可以继续设置 HTTPS 密码设置 HTTPS 密码 HTTPS 密码是使用 HTTPS 协议和代码托管服务端交互的凭证, 设置步骤如下 : 1. 进入代码托管首页, 单击设置我的 HTTPS 密钥, 显示 HTTPS 密钥管理页面 a. 如果您是第一次进行设置, 则输入 2 次 HTTPS 密码保存即可 b. 如果您不是第一次进行设置, 可以单击修改对密码进行重置 c. 单击修改, 您需要输入邮箱验证码, 重新设置新密码保存即可 1.3 Git 本地研发场景背景介绍在 DevCloud 云端创建一个 README 文件的空仓库, 然后架构师或者项目负责人需要把本地框架代码推送到这个空仓库, 最后, 其他开发人员将云端架构代码克隆到本地, 进行增量应用开发文档版本 04 ( ) 版权所有华为技术有限公司 7

11 说明 Git 代码传输支持 SSH 和 HTTPS 两种传输协议, 本节基于 SSH 传输协议进行的操作如果想使用 HTTPS 方式, 直接下载 HTTPS 密码, 当克隆推送代码时直接输入 HTTPS 用户名密码即可同一仓库 SSH 和 HTTPS 的地址不同推送架构代码 1. 打开本地框架代码, 确保根目录名 (DevCloud) 与云端创建的代码仓库名一致, 在根目录下右键打开 Git bash 终端, 如下图所示 2. 推送本地代码到云端在当前 Git Bash 终端依次输入如下命令 : a. 初始化本地代码仓库, 执行该命令后, 在 D:/code/DevCloud/ 下多了一个.git 文件夹 $ git init b. 关联云端代码仓库 $ git remote add origin CodeHubUrl 仓库地址 CodeHubUrl 如下图所示单击红色方框处获取 c. 推送代码到云仓库 $ git add. $ git commit -m "init project" $ git branch --set-upstream-to=origin/master master $ git pull --rebase $ git push 文档版本 04 ( ) 版权所有华为技术有限公司 8

代码提交一次修改被成功提交到远端仓库会历经四个阶段 : 1 本地工作区 > 2 缓存区 > 3 版本库 > 4 远端版本库通过执行相应的

12 克隆代码开发人员在本地准备克隆云端架构代码 1. 在准备把代码克隆到的目标文件夹下, 右键打开 Git bash 终端, 如下图所示 2. 克隆仓库,URL 地址如下图所示单击红色方框处获取 $ git clone CodeHubUrl // 将代码从远端仓库 clone 到本地代码提交一次修改被成功提交到远端仓库会历经四个阶段 : 1 本地工作区 > 2 缓存区 > 3 版本库 > 4 远端版本库通过执行相应的 Git 命令, 文件在这四个区域跳转, 并呈现不同的状态, 如下图所示文档版本 04 ( ) 版权所有华为技术有限公司 9

13 主要涉及如下三步操作 : 1. #git add/rm filename // 将新增修改或者删除的文件增加到暂存区 2. #git commit m commit message // 将已暂存的文件提交到本地仓库 3. #git push // 将本地代码仓库修改推送到远端仓库分支操作新建分支 Git 新建分支的本质就是创建一个指向最后一次提交的可变指针, 所以,Git 分支的创建不是复制版本库的内容, 仅仅是新建了一个指针, 它以 40 个字符长度 SHA-1 字串形式保存在文件中 #git branch branchname commitid 基于 commitid 即某一个全球版本号拉出新分支, 如果没有 commitid 则基于当前分支的 HEAD 拉出新分支例如, 新建 feature 分支, 执行的命令为 git branch feature, 如下图所示切换分支命令如下 #git checkout branchname 例如, 切换到 feature 分支, 执行的命令为 git checkout feature, 如下图所示文档版本 04 ( ) 版权所有华为技术有限公司 10

分支合并无论哪种工作流都会涉及到分支合并 ( 把一个分支中的修改整合到当前分支 ), 主要有两种方法 : 三方合并 (merge) 和衍合 (rebase) 通过对同一种场景进行不同操作体会两种合并方法的区别场景 :master 分支新增了 C4 节点, hotfix 分支新增了 C3 节点, 现将 hotfix 分支合并到 master 分支 : a.

14 分支合并无论哪种工作流都会涉及到分支合并 ( 把一个分支中的修改整合到当前分支 ), 主要有两种方法 : 三方合并 (merge) 和衍合 (rebase) 通过对同一种场景进行不同操作体会两种合并方法的区别场景 :master 分支新增了 C4 节点, hotfix 分支新增了 C3 节点, 现将 hotfix 分支合并到 master 分支 : a. 三方包括 hotfix 新增节点 C3,master 新增节点 C4, 以及两者的共同祖先节点 C2 这种合并操作简单, 但新增合并节点 C5, 形成了环形, 版本记录可读性差, 如下图所示 #git checkout master #git merge hotfix b. 衍合先将 master 分支新增节点 C4 以补丁形式保存在.git/rebase 目录中, 然后同步 hotfix 分支最新代码, 再应用补丁 C4, 如下图所示 #git checkout master #git rebase hotfix 冲突解决 a. 场景一 : 两个合并分支修改了同一行代码解决方法 : 文档版本 04 ( ) 版权所有华为技术有限公司 11

15 i. 分析哪种修改方法正确, 手动合并 ii. 提交修改 b. 场景二 : 文件被重命名为不同的名字解决方法 : i. 确认哪个名字是正确的, 删除错误的 ii. 提交修改 1.4 Git 工作流 Git 工作流概述什么是 Git 工作流? 你可以理解为代码管理的分支策略, 它不仅仅是版本管理范畴, 更服务于项目流程管理和团队协同开发所以, 有必要制定适合自己研发场景的工作流下面介绍四种工作流的工作方式优缺点, 以及使用中的一些注意事项集中式工作流功能分支工作流 Gitflow 工作流 (Devcloud 推荐 ) Forking 工作流集中式工作流工作方式优点研发团队可以根据实际研发场景制定合理的工作流, 能有效提高项目管理水平和团队协同开发能力, 并通过华为软件开发云 CodeHub 平台, 高效安全的管理代码资产, 将更多的精力集中在业务开发上, 实现持续集成持续交付和快速迭代的目标集中式工作流适合 5 人左右小开发团队, 或是刚从 SVN 工具转型为 Git 的团队, 它只有一个默认的 maste 分支 ( 相当于 svn 的 trunk 主分支 ), 所有人的修改都是在 master 分支上进行的但是, 这种工作流无法充分发挥 git 优势和多人协同, 不推荐使用开发人员将 master 分支从中央仓库克隆到本地, 修改完成后再推送回中央仓库 master 分支不涉及分支交互操作缺点不适合人员较多的团队, 当人员 10+ 时, 解决开发人员之间的代码冲突会耗费很多时间 master 分支提交频繁 master 分支不稳定, 不利于集成测试文档版本 04 ( ) 版权所有华为技术有限公司 12

16 Tips: 如何尽量避免产生冲突和不合理的提交历史? 开发人员在开发一个新功能之前, 一定要在本地同步中央仓库最新代码, 使自己的工作基于最新的代码之上 ; 开发完成后, 在提交新功能到中央仓库前, 需要先 fetch 中央库的新增提交, 并 rebase 自己的提交这样做的目的是, 把自己的修改加到中央仓别人已经提交的修改之上, 使最终的提交记录是一个完美的线性历史, 而不是环形, 工作流举例如下图所示功能分支工作流 1. 开发人员 A 和开发人员 B 同时在某个时间拉取了中央仓库的代码 2. 开发人员 A 先完成了自己的工作, 并提交到中央仓库 3. 开发人员 B 需要在本地执行 git pull rebase 中央仓库的新提交, 这时开发人员 B 的本地仓库就包含了开发人员 A 修改的内容, 并在 A 的基础上增加了自己的修改 4. 开发人员 B 将代码推送到中央仓库通过新建几个功能分支, 增加开发者的交流和协作, 它的理念是所有的功能开发都应该在 master 分支外的一个独立分支进行, 这种方式隔离了开发者的工作空间不被互相干扰, 保证了 master 分支的稳定性工作方式开发人员每次在开始新功能开发前, 需要在 master 分支上拉取一个新分支, 并起个有描述性的名字, 比如 video-output 或 issue-#1061, 这样可以让分支用途明确功能分支不但存在开发人员本地仓库, 也应该推送到中央仓库, 这样就可以在代码不合入 master 分支的情况下与其他开发人员分享代码优点分支合并前可以使用 pull request 进行 code review 降低了 master 分支的提交频率缺点只有一个 master 分支作为集成, 仍然不是很稳定, 不适合大型开发文档版本 04 ( ) 版权所有华为技术有限公司 13

1.4.4 Gitflow 工作流 Gitflow 一般用于管理大型项目, 它为不同的分支分配一个很明确的工作角色, 并定义分支之间什么时候进行交互, 如 Gitflow 工作流如下图所示工作方式 master 分支 : 生产分支, 最稳定的版本, 一直是 ready to deploy 状态不接受开发人员直接 commit, 只接受从其他分支 merge 操作在很多企业中,

17 1.4.4 Gitflow 工作流 Gitflow 一般用于管理大型项目, 它为不同的分支分配一个很明确的工作角色, 并定义分支之间什么时候进行交互, 如 Gitflow 工作流如下图所示工作方式 master 分支 : 生产分支, 最稳定的版本, 一直是 ready to deploy 状态不接受开发人员直接 commit, 只接受从其他分支 merge 操作在很多企业中, 这个分支被默认开启分支保护, 只有维护者可以操作 hotfix 分支 : 从 master 分支拉取的临时修复分支, 用于解决一线紧急 bug bug 解决后需要合入 master 分支并打上新的版本号, 这个修改也需要同时合入 develop 分支 develop 分支 : 从 master 分支拉取的开发分支, 用于功能集成包含所有要发布到下一个 Release 的代码用于开发集成系统测试 release 分支 : 临近既定的发布日, 就从 develop 分支上拉取一个 release 分支, 任何不在当前分支中的新功能都推到下个发布中 release 分支用于发布, 所以从当前时间点之后新的功能不能再加到这个分支上, 这个分支只做 Bug 修复文档生成和其它面向发布的任务当对外发布的工作都完成了,release 分支合并到 master 分支并分配一个版本号打好 Tag; 另外, 这些从 release 分支新做的修改要反向合并回 develop 分支 feature 分支 : 开发者使用的特性分支, 父分支是 develop 分支, 当新功能完成时, 合入 develop 分支新功能提交从不直接与 master 分支交互开发人员提交新功能的两种途径 : 文档版本 04 ( ) 版权所有华为技术有限公司 14

18 团队有专人 review 审核新功能 a. 开发人员将 feature 分支推送到华为软件开发云代码托管平台 ( 中央仓库 ) b. 发起一个从 feature 分支合并到 develop 分支的合并请求, 并指给 review 专员说明 DevCloud 代码托管中支持合并请求功能, 直接选择源和目的分支, 仓库管理员 ( 项目经理创建仓库的开发人员被给予仓库管理权限的开发人员 ) 有权限接受此合并请求 c. review 专员审核如果通过, 将 feature 分支的新功能合并到 develop 分支, 并删除 feature 分支 ; 如果未通过, 拒绝该请求并注明拒绝原因开发人员自审核新功能 a. 开发人员在本地仓库将 feature 分支合并到 develop 分支, 并删除 feature 分支 b. 将本地 develop 分支的修改推送到华为软件开发云代码托管平台 ( 中央仓库 ) 优点缺点使用一个用于发布准备的专门分支 (release 分支 ), 使得一个团队可以在完善当前的发布版本的同时, 可以在 develop 分支并行继续开发下个版本的功能这也打造了可视化的发布阶段, 团队成员都可以在仓库网状结构中可以看到发布状态使用紧急修复分支 (hotfix 分支 ) 让团队可以处理紧急问题的同时而不打断其它工作或是等待下一个发布再合入 hotfix 修改我们可以把 hotfix 分支想成是一个直接在 master 分支上处理的临时发布大型项目人员协作频繁, 流程较多, 合理的多角色分支帮助研发有条不紊进行更符合 devops 理念学习成本较高如果团队不遵守使用约定, 带来的影响更大 Forking 工作流 Forking 工作流区别于前三种工作流的最大特点是每个开发人员都有一个从公共仓库 fork 出来的属于自己的公共仓 Forking 工作流适合外包众包以及众创和开源场景接包方的开发人员从项目公共仓 fork 自己的公共仓库进行操作, 并不需要被项目公共仓直接授权,Forking 工作流如下图所示文档版本 04 ( ) 版权所有华为技术有限公司 15

19 工作方式 1. 将项目公共仓 fork 出一个个人公共仓 2. 将个人公共仓 clone 到本地仓库 3. 操作本地仓库, 修改完成后提交到个人公共仓 4. 为个人公共仓提交一个 pull request 给项目维护者, 申请代码合入项目公共仓 5. 项目维护者在本地 review 验证本地提交, 审核通过后 push 进入项目公共仓说明如果开发人员 A 的代码未被审核通过合入公共仓库, 而此代码对开发人员 B 有借鉴作用, 开发人员 B 可以直接从开发人员 A 的个人公共仓拉取代码优点开发人员之间若需要代码协作, 可以直接从其他人的个人公共仓拉取, 无需等到代码提交到项目公共仓项目公共仓无需为每个代码贡献者授权项目维护者通过审核 pull request 成为代码安全的重要防线仓库分支的选择可以根据项目实际情况综合使用前三种工作流缺点提交开发人员代码到最终版本库的周期较长, 步骤繁琐文档版本 04 ( ) 版权所有华为技术有限公司 16

Git 原理简介 Git 是一种分布式版本控制系统每个克隆的仓库都包含有整个仓库的所有数据任何修改先提交在本地, 再推送到服务器创建和切换分支合并修改相当方便而且快速本文档中第一次出现的术语将以蓝色斜体标出术语的含义是单一的明确的不可替代的 1

Git 原理简介 Git 是一种分布式版本控制系统每个克隆的仓库都包含有整个仓库的所有数据任何修改先提交在本地, 再推送到服务器创建和切换分支合并修改相当方便而且快速本文档中第一次出现的术语将以蓝色斜体标出术语的含义是单一的明确的不可替代的 1 Git 原理简介 Git 是一种分布式版本控制系统每个克隆的仓库都包含有整个仓库的所有数据任何修改先提交在本地, 再推送到服务器创建和切换分支合并修改相当方便而且快速本文档中第一次出现的术语将以蓝色斜体标出术语的含义是单一的明确的不可替代的 1 Git 仓库结构举例 git@my.server:bob/my.git master A B C 2 Git 仓库结构相对本地已克隆的仓库而言,