工蜂集成TAPD、Jenkins实现特性驱动开发手册

一、前言

本文主要是对TAPD(腾讯敏捷产品研发平台)以及工蜂（类似于GitLab的仓库管理系统，也是基于Git的）的使用讲解以及基于两种平台实现特性驱动开发，并通过jekins实现自动构建、部署(CI/CD)。

二、GitLab工作流

1.什么是GitLab工作流？

工作流，英文单词flow，寓意像河流一样流动，有明确的流向和过程,不会杂乱无章。
GitLab 是一个基于 git 的仓库管理系统，而GitLab工作流是在软件开发过程中，在使用 GitLab 作为代码托管平台时，可以采取的动作的一个逻辑序列。简单来说就是如何从GitLab上获取代码、将自己的代码更新到GitLab以及分支管理等一系列基于Git 的方法和策略。

2.Git、GitHub和GitLab工作流的区别

由于GitHub以及GitLab都是基于Git的，所以都集成了Git提交代码的工作流（见下图2-1），这三者最大的区别在于分支的管理策略不同;

1>Git工作流由于缺乏共有的约定，会产生较多的开发分支，会导致分支管理混乱，合并的时候可能会出现遗漏等问题；其次必须使用develop分支来开发，而不是master分支，开发时不停切换分支是很麻烦的。

2>GitHub工作流只有一个feature分支和一个master分支，简单而干净，但是这种工作流中仍然有很多问题没有解决，例如部署、环境、发布和issue的管理；

3>GitFlow通过下行(downstream)工作流和“upstream first”策略解决了GitHub部署和环境的问题以及Git工作流合并代码可能产生的疏漏。

图2-1 Git Commit 工作流

图2-2 三种工作流比较

3. GitLab为软件开发阶段提供的解决方案

1>IDEA： 每一个从点子开始的项目，通常来源于一次闲聊。在这个阶段，GitLab 集成了 Mattermost;
2>ISSUE： 最有效的讨论一个点子的方法，就是为这个点子建立一个工单讨论。你的团队和你的合作伙伴可以在 工单追踪器(issue tracker) 中帮助你去提升这个点子;
3>PLAN： 一旦讨论得到一致的同意，就是开始编码的时候了。但是等等！首先，我们需要优先考虑组织我们的工作流。对于此，我们可以使用 工单看板(Issue Board);
4>CODE： 现在，当一切准备就绪，我们可以开始写代码了。
5>COMMIT： 当我们为我们的初步成果欢呼的时候，我们就可以在版本控制下，提交代码到功能分支了;
6>TEST： 通过 GitLab CI，我们可以运行脚本来构建和测试我们的应用。
7>REVIEW： 一旦脚本成功运行，我们测试和构建成功，我们就可以进行 代码复审(code review) 以及批准;
8>STAGING：： 现在是时候将我们的代码部署到演示环境[来检查一下，看看是否一切就像我们预估的那样顺畅——或者我们可能仍然需要修改。
9>PRODUCTION： 当一切都如预期，就是部署到生产环境的时候了;
10>FEEDBACK： 现在是时候返回去看我们项目中需要提升的部分了。我们使用周期分析(Cycle Analytics)来对当前项目中关键的部分进行的反馈。

三、FDD(特性驱动开发)

1.什么是FDD?

特征驱动开发（FDD-Feature Driven Development）方法是敏捷软件开发过程中的一种，是由Jeff de Luca 、Eric Lefebvre、Peter Coad共同开发的。它强调特性驱动，快速迭代，即能保证快速开发，又能保证适当文档和质量，非常适合中小型团队开发管理。它提出的每个功能开发时间不超过两周，为每个用例user case限定了粒度，具有良好可执行性，也可以对项目的开发进程进行精确及时地监控。它抓住了软件开发的核心问题领域，即正确和及时地构造软件。FDD还打破了传统的将领域和业务专家/分析师与设计者和实现者隔离开来的壁垒。分析师被从抽象的工作中解脱出来，直接参与到开发人员和用户所从事的系统构造工作中。

2.Feature的理解

在FDD中，Feature（特征）是一个基本的开发单位，是（FDD）项目中的一个增量，是指用户眼中最小的有用的功能，可以在很短时间内实现（一般在两周之内）。

3.FDD过程

FDD是一个模型驱动( model-driven)、短期迭代(short-iteration)的过程。 注意，FDD是一个开发过程，过程总是有起点和终点，FDD的起点是起源于创建一个全局的模型轮廓（不要求很精确，大概模样就可以），然后是周期低于两周的一系列的"design by feature, build by feature"的迭代，逐渐丰富模型功能内容。

图3-1 FDD过程

四、基于工蜂和TAPD实现特性驱动开发

1.什么是工蜂？

工蜂是腾讯的一款基于 Git 的在线代码托管工具，包含代码提交/存储/下载/复刻/分支/历史/比对/合并等功能。可一站式完成对代码及代码质量管理，项目及项目人员管理，提升研发效率，类似于GitLab。

2.什么是TAPD?

TAPD（Tencent Agile Product Development）全名为腾讯敏捷产品研发平台，提供看板、在线文档、敏捷需求规划、迭代计划&跟踪、任务工时管理、缺陷跟踪管理、测试计划&用例、持续集成、持续交付&部署等丰富的可配置功能。并提供轻量协作解决方案、敏捷研发解决方案、Devops解决方案。

3.工蜂和TAPD集成过程

1>ASSOCIATION:将TAPD上的项目与工蜂上的源码相关联；
2>ISSUE：在TAPD上建立ISSUE(需求/任务/缺陷);
3>BRANCH:在本地创建特性分支；
4>CODE：编写代码；
5>COMMIT:按固定的备注格式提交代码，并PUSH到远程分支，发起合并请求；
6>TEST：通过 Jenkins CI，运行脚本来构建和测试commit的代码。
7>REVIEW： 一旦测试和构建成功，就可以进行 代码复审(code review) 以及批准。
8>FEEDBACK： 返回TAPD查看ISSUE关联的源码提交记录

4.什么是Jenkins

Jenkins是一款由Java编写的开源的持续集成工具, Jenkins提供了软件开发的持续集成服务。它运行在Servlet容器中（例如Apache Tomcat）。它支持软件配置管理（SCM）工具（包括AccuRev SCM、CVS、Subversion、Git、Perforce、Clearcase和RTC），可以执行基于Apache Ant和Apache Maven的项目，以及任意的Shell脚本和Windows批处理命令

5.工蜂和Jenkins集成过程

1> 在工蜂上创建任务创建特性分支，通过代码库根目录的Jenkinsfile与Jenkins关联， Jenkinsfile内容样例：

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        sh "echo ${env.JENKINS_URL}"
        sh 'mvn package'
      }
    }
    stage('Post-Build') {
    when {
      anyOf {
        tag '*-release'
        tag '*-beta'
      }
    }
      parallel {
        stage('Deploy') {
          steps {
            sh 'echo Deploying'
            sh 'mvn --version'
            sh 'java -version'
          }
        }
        stage('Sonar') {
          steps {
            sh 'echo "Sonar TBD" '
          }
        }
      }
    }
  }
  post {
    failure {
      echo '!!!FAILED!!!'

    }

  }
}

Jenkinsfile的内容就是Jenkins 对应Pipeline任务的执行脚本，包括构建，发布，Sonar代码检查，回写构建结果到工蜂。
需要根据代码库名称修改变量GIT_PATH：
GIT_PATH=‘http://git.code.oa.com/api/v3/projects/eagle_proj%2Fjava-pipeline-demo’
里的项目名称（只修改加粗部分）
2> 在Jenkons的Blueocean界面创建多分支Pipeline 任务


3> 配置Jenkins访问工蜂的API Token
a) 从工蜂里拷贝当前项目成员的private token

b) 将从工蜂里拷贝的token存入Jenkons 凭证库，截图里的ID即Jenkinsfile里的credentialsId变量名；


4> 配置工蜂的web hook

5> 配置完成后，开发人员提交push代码即可在当前分析的Commit信息上看到构建反馈的结果；

6> 开发人员查看当前分支Commit，可以检查构建结果，点击图标可以打开Jenkins构建详细信息。 开发人员根据需要重新修改代码并提交，再次触发Jenkins构建，直到构建正确再发起合并请求。

7> 审批人在Merge Request流程上可以看到明显的错误信息并可以点击“Detail”查看构建错误

五、详细步骤

1.ASSOCIATION

说明：关联TAPD和工蜂源码
1>登录TAPD门户网站，选择需要关联工蜂源码的项目；

图5-1-1 关联TAPD和工蜂源码

2>点击页面上方右侧的齿轮图标，然后在左侧菜单栏选择应用设置，点击启动项目应用，进行项目应用设置；

图5-1-2 关联TAPD和工蜂源码

3>选择右侧待启用应用窗口中的源码块，拖动至下方更多显示的窗口中，点击保存按钮

图5-1-3 关联TAPD和工蜂源码

4>执行上一步后，齿轮图标消失，会多出个更多选项，选择更多下拉框中的源码，然后点击配置按钮（此操作需要项目的管理员权限）；

图5-1-4 关联TAPD和工蜂源码

5>启动GIT源码配置，点击关联GIT项目，选择对话框中需要关联的GIT源码路径（此操作需要有对应的git源码权限），保存确定，至此，TAPD关联工蜂代码操作完成

图5-1-5 关联TAPD和工蜂源码

2.ISSUE

说明：创建TAPD问题（需求/任务/缺陷）
1>添加需求、任务、缺陷到更多显示中；

图5-2-1 创建TAPD问题

2>点击上方的+号按钮，选择创建需求（任务、缺陷类似）；

图5-2-2 创建TAPD问题
3>填写需求的相关信息，提交需求（需求创建成功后需要记住需求ID）；

图5-2-3 创建TAPD问题

3.BRANCH

说明：创建特性分支
1>登录工蜂门户网站，选择需要clone的项目，复制项目的远程仓库地址

图5-3-1 创建特性分支
2>选择要clone到的本地文件夹，右键单击，选择Git Bash Here(需提前安装好git)

图5-3-2 创建特性分支

3>输入命令 git clone [工蜂代码仓库地址]，回车运行完成后，远程仓库就下载到本地了。

图5-3-3 创建特性分支

4>输入cd命令进入项目文件夹，可以看到目前处在该项目的master分支上，创建需求的特性分支并切换到特性分支上。
Git命令：git checkout -b [特性分支名称]

图5-3-4创建特性分支

5>在项目根目录下创建Jenkinsfile文件(push代码时触发jenkins构建/单元测试/sonar代码检查)，文件见第四章第5节工蜂和Jenkins集成过程；

4. CODE

说明：编码
这里仅做测试，修改项目下的README文件夹，向文件末尾追加几个空格，并用git status命令查看文件是否被修改。

图5-4 编码

5. COMMIT&TEST

说明：提交代码并自动构建/单元测试/代码检查
提交代码，参考前面图1-1 Git Commit 工作流，除了图中的三个步骤，在push代码前需要同步远程master分支代码，以防止别人修改同样的文件并提交到master分支造成代码冲突
1>将修改的内存保存到暂存区,用 git status追踪文件变化；
Git命令：git add . （.代表当前目录，意思是当前目录下的所有修改的文件都会被添加到暂存区）

图5-5-1 提交代码并自动构建

2>将暂存区的内容提交到本地仓库；
Git命令：git commit -m [备注] （需注意备注内容必须满足对应的关键字，才能与TAPD的ISSUE关联，具体格式如下）
①需求: --story=[story id] --user=[昵称] 或者 --story=[story id 1],[story id 2] --user=[昵称] (关联多个需求)；
②任务：–task=[task id] --user=[昵称] 或者 --task=[task id 1],[task id 2] --user=[昵称] (关联多个任务)；
③缺陷：–bug=[bug id] --user=[昵称] 或者 --bug=[bug id 1],[bug id 2] --user=[昵称] (关联多个缺陷)；
(id为前面在TAPD创建问题时得到的问题id)

图5-5-2-1 提交代码并自动构建

注：
commit的备注可以在之前TAPD创建的问题中点击源码提交关键字即可复制到粘贴板,具体如下图：

图5-5-2-2 提交代码并自动构建

3>合并master分支到特性分支,如有冲突需先解决冲突；
Git命令：git pull origin master （此命令包含两个操作，第一步操作拉取远程master分支代码，第二部合并到特性分支，需注意此命令没有将远程master分支同步到本地master分支，如果切换到本地master分支，需要再pull一遍）

图5-5-3 提交代码并自动构建

4>push到远程特性分支
Git 命令：git push origin [远程分支名称]

图5-5-4 提交代码并自动构建

5>登录jenkins门户网站，查看此次代码提交构建运行情况，若有错误需要解决错误，然后再发起合并请求(构建流程有jenkinsfile定义)；

图5-5-5 提交代码并自动构建

6>发起合并请求，登录工蜂门户网站
①点击左上角+号图标>单击New Merge request>选择Source branch(创建的特性分支)>点击Compare branches

图5-5-6-1 提交代码并自动构建

②填写描述信息，选择批准以及复核代码的人

图5-5-6-2 提交代码并自动构建

③提交合并请求

图5-5-6-3 复核并批准提交请求

6. REVIEW

说明:代码复核以及批准合并请求
1>登录工蜂门户网站>点击左侧菜单栏的Merge Requests>选择所要合并的特性分支（这里是Validate）

图5-6-1 复核并批准提交请求

2>由于代码复核人员填写的是本人，所以无需复核，直接进行允许合并请求

图5-6-2 复核并批准提交请求

7. FEEDBACK

说明：回顾TAPD需求，查看需求相应的提交记录，进行复查
选择项目>点击上方需求菜单栏>选择下方更多选项卡>点击git提交按钮，查看相应的git提交记录

图5-7 回顾需求与代码提交记录

六、Git常用命令

1.git clone

 获取一个url对应的远程Git repo, 创建一个local copy.
 一般的格式是git clone [url].
 clone下来的repo会以url最后一个斜线后面的名称命名,创建一个文件夹,如果想要指定特定的名称,可以git clone [url] newname指定.

2.git status

 查询repo的状态.
 git status -s: -s表示short, -s的输出标记会有两列,第一列是对staging区域而言,第二列是对working目录而言.

3.git log

 show commit history of a branch.
 git log --oneline --number: 每条log只显示一行,显示number条.
 git log --oneline --graph:可以图形化地表示出分支合并历史.
 git log branchname可以显示特定分支的log.
 git log --oneline branch1 ^branch2,可以查看在分支1,却不在分支2中的提交.^表示排除这个分支(Window下可能要给^branch2加上引号).
 git log --decorate会显示出tag信息.
 git log --author=[author name] 可以指定作者的提交历史.
 git log --since --before --until --after 根据提交时间筛选log.
 --no-merges可以将merge的commits排除在外.
 git log --grep 根据commit信息过滤log: git log --grep=keywords
 默认情况下, git log --grep --author是OR的关系,即满足一条即被返回,如果你想让它们是AND的关系,可以加上--all-match的option.
 git log -S: filter by introduced diff.
 比如: git log -SmethodName (注意S和后面的词之间没有等号分隔).
 git log -p: show patch introduced at each commit.
 每一个提交都是一个快照(snapshot),Git会把每次提交的diff计算出来,作为一个patch显示给你看.
 另一种方法是git show [SHA].
 git log --stat: show diffstat of changes introduced at each commit.
 同样是用来看改动的相对信息的,--stat比-p的输出更简单一些.

4.git add

 在提交之前,Git有一个暂存区(staging area),可以放入新添加的文件或者加入新的改动. commit时提交的改动是上一次加入到staging area中的改动,而不是我们disk上的改动.
 git add .
 会递归地添加当前工作目录中的所有文件.

5.git fetch

 download new branches and data from a remote repository.
 可以git fetch [alias]取某一个远程repo,也可以git fetch --all取到全部repo
 fetch将会取到所有你本地没有的数据,所有取下来的分支可以被叫做remote branches,它们和本地分支一样(可以看diff,log等,也可以merge到其他分支),但是Git不允许你checkout到它们. 

6.git pull

 fetch from a remote repo and try to merge into the current branch.
 pull == fetch + merge FETCH_HEAD
 git pull会首先执行git fetch,然后执行git merge,把取来的分支的head merge到当前分支.这个merge操作会产生一个新的commit.    
 如果使用--rebase参数,它会执行git rebase来取代原来的git merge.

7.git commit

 提交已经被add进来的改动.
 git commit -m “the commit message"
 git commit -a 会先把所有已经track的文件的改动add进来,然后提交(有点像svn的一次提交,不用先暂存). 对于没有track的文件,还是需要git add一下.
 git commit --amend 增补提交. 会使用与当前提交节点相同的父节点进行一次新的提交,旧的提交将会被取消.

8.git reset

 undo changes and commits.
 这里的HEAD关键字指的是当前分支最末梢最新的一个提交.也就是版本库中该分支上的最新版本.
 git reset HEAD: unstage files from index and reset pointer to HEAD
 这个命令用来把不小心add进去的文件从staged状态取出来,可以单独针对某一个文件操作: git reset HEAD - - filename, 这个- - 也可以不加.
 git reset --soft
 move HEAD to specific commit reference, index and staging are untouched.
 git reset --hard
 unstage files AND undo any changes in the working directory since last commit.
 使用git reset —hard HEAD进行reset,即上次提交之后,所有staged的改动和工作目录的改动都会消失,还原到上次提交的状态.
 这里的HEAD可以被写成任何一次提交的SHA-1.
 不带soft和hard参数的git reset,实际上带的是默认参数mixed.

 总结:
 git reset --mixed id,是将git的HEAD变了(也就是提交记录变了),但文件并没有改变，(也就是working tree并没有改变). 取消了commit和add的内容.
 git reset --soft id. 实际上，是git reset –mixed id 后,又做了一次git add.即取消了commit的内容.
 git reset --hard id.是将git的HEAD变了,文件也变了.
 按改动范围排序如下:
 soft (commit) < mixed (commit + add) < hard (commit + add + local working)

9.git revert

 反转撤销提交.只要把出错的提交(commit)的名字(reference)作为参数传给命令就可以了.
 git revert HEAD: 撤销最近的一个提交.
 git revert会创建一个反向的新提交,可以通过参数-n来告诉Git先不要提交.

10.git rm

 git rm file: 从staging区移除文件,同时也移除出工作目录.
 git rm --cached: 从staging区移除文件,但留在工作目录中.
 git rm --cached从功能上等同于git reset HEAD,清除了缓存区,但不动工作目录树.

11.git clean

 git clean是从工作目录中移除没有track的文件.
 通常的参数是git clean -df:
 -d表示同时移除目录,-f表示force,因为在git的配置文件中, clean.requireForce=true,如果不加-f,clean将会拒绝执行.

12.git mv

 git rm - - cached orig; mv orig new; git add new

13.git stash

 把当前的改动压入一个栈.
 git stash将会把当前目录和index中的所有改动(但不包括未track的文件)压入一个栈,然后留给你一个clean的工作状态,即处于上一次最新提交处.
 git stash list会显示这个栈的list.
 git stash apply:取出stash中的上一个项目(stash@{0}),并且应用于当前的工作目录.
 也可以指定别的项目,比如git stash apply stash@{1}.
 如果你在应用stash中项目的同时想要删除它,可以用git stash pop

 删除stash中的项目:
 git stash drop: 删除上一个,也可指定参数删除指定的一个项目.
 git stash clear: 删除所有项目.

14.git branch

 git branch可以用来列出分支,创建分支和删除分支.
 git branch -v可以看见每一个分支的最后一次提交.
 git branch: 列出本地所有分支,当前分支会被星号标示出.
 git branch (branchname): 创建一个新的分支(当你用这种方式创建分支的时候,分支是基于你的上一次提交建立的). 
 git branch -d (branchname): 删除一个分支.
 删除remote的分支:
 git push (remote-name) :(branch-name): delete a remote branch.
 这个是因为完整的命令形式是:
 git push remote-name local-branch:remote-branch
 而这里local-branch的部分为空,就意味着删除了remote-branch

15.git checkout

git checkout (branchname)

切换到一个分支.
git checkout -b (branchname): 创建并切换到新的分支.
这个命令是将git branch newbranch和git checkout newbranch合在一起的结果.
checkout还有另一个作用:替换本地改动:
git checkout –
此命令会使用HEAD中的最新内容替换掉你的工作目录中的文件.已添加到暂存区的改动以及新文件都不会受到影响.
注意:git checkout filename会删除该文件中所有没有暂存和提交的改动,这个操作是不可逆的.

16.git merge

 把一个分支merge进当前的分支.
 git merge [alias]/[branch]
 把远程分支merge到当前分支.

 如果出现冲突,需要手动修改,可以用git mergetool.
 解决冲突的时候可以用到git diff,解决完之后用git add添加,即表示冲突已经被resolved.

17.git tag

 tag a point in history as import.
 会在一个提交上建立永久性的书签,通常是发布一个release版本或者ship了什么东西之后加tag.
 比如: git tag v1.0
 git tag -a v1.0, -a参数会允许你添加一些信息,即make an annotated tag.
 当你运行git tag -a命令的时候,Git会打开一个编辑器让你输入tag信息.
 
 我们可以利用commit SHA来给一个过去的提交打tag:
 git tag -a v0.9 XXXX

 push的时候是不包含tag的,如果想包含,可以在push时加上--tags参数.
 fetch的时候,branch HEAD可以reach的tags是自动被fetch下来的, tags that aren’t reachable from branch heads will be skipped.如果想确保所有的tags都被包含进来,需要加上--tags选项.

18.git rebase

 --rebase不会产生合并的提交,它会将本地的所有提交临时保存为补丁(patch),放在”.git/rebase”目录中,然后将当前分支更新到最新的分支尖端,最后把保存的补丁应用到分支上.
 rebase的过程中,也许会出现冲突,Git会停止rebase并让你解决冲突,在解决完冲突之后,用git add去更新这些内容,然后无需执行commit,只需要:
 git rebase --continue就会继续打余下的补丁.
 git rebase --abort将会终止rebase,当前分支将会回到rebase之前的状态.

19.git push

 push your new branches and data to a remote repository.
 git push [alias] [branch]
 将会把当前分支merge到alias上的[branch]分支.如果分支已经存在,将会更新,如果不存在,将会添加这个分支.
 如果有多个人向同一个remote repo push代码, Git会首先在你试图push的分支上运行git log,检查它的历史中是否能看到server上的branch现在的tip,如果本地历史中不能看到server的tip,说明本地的代码不是最新的,Git会拒绝你的push,让你先fetch,merge,之后再push,这样就保证了所有人的改动都会被考虑进来.