内容


使用 Jazz API 将历史性数据从 CMVC 转移至 Rational Team Concert 项目

Comments

概述

随着越来越多的软件开发团队开始涉足基于 IBM® Rational Team Concert™ 网络的协作软件,以管理完整的软件开发生命周期,关注转移历史性数据成为大家共同的关注点。许多的项目多年使用其他不同的软件配置管理(SCM)系统。因此,在那些 SCM 系统中会有大量的历史性数据。怎样将这些数据转移至 Rational Team Concert,成为这些项目团队所面临的一个顶级的挑战。

本文基于我们将历史性数据从配置管理版本控制(CMVC)转移至 Rational Team Concert 在线系统的经验。它描述了怎样从 CMVC 导出历史性数据,导入到 Rational Team Concert,而不用失去不同代码工件之间的联系。本文概括的转移步骤,使用 CMVC 客户端 APIs 和 Rational Team Concert APIs,有助于从其他 SCM 系统到 Rational Team Concert 项目的转移过程。

CMVC 与 Rational Team Concert 之间的比较

CMVC 基础

配置管理版本控制(CMVC)是一种著名的软件配置管理(SCM)产品。它集成了分布式开发环境下的四个方面,以促进产品开发生命周期所有阶段的协调:

  • 配置管理
  • 版本控制
  • 变更控制
  • 问题追踪

在 CMVC 中,源代码管理中引入了以下的概念与对象:

  • 构件提供开发数据的组织和控制手段。
  • 版本包含了与产品相关活动的文件。
  • 缺陷用于记录关于报告问题的信息。
  • 特性用于记录关于预期改善的信息。

Rational Team Concert 基础知识

Rational Team Concert 是下一代的协作性程序生命周期管理产品。它是在 IBM® Rational® Jazz™ 技术平台上运行的。Jazz 是一种可评测,可扩展的团队协作性平台,它将软件开发生命周期之间的任务集成了起来。

Rational Team Concert 使得交换信息以及团队协作变得更加容易。如果有请求更改时,您和其他的团队成员将会自动收到变更的通知。您可以在交谈中参考更改,并将其与相关的工件联系起来。业务涉众也可以自动收到他们感兴趣的任务更改状态的信息。

软件开发生命周期的许多方面,在单个环境中收到了大多数人的关注,这些环境包括敏捷开发规划,进程定义,源控制,缺陷报告追踪,构建管理以及报告。您可以追踪并管理不同工件之间的联系,远程监听开发过程,并自动收集项目的信息。Rational Team Concert 使用基于 Eclipse 的客户端界面,Microsoft® Visual Studio 客户端界面,以及一个网络界面,来支持进程配置和定制。

两者之间的比较

CMVC 与 Rational Team Concert 提供了强大的 SCM 功能,但是 Rational Team Concert 将更多的注意力放在协作和合作上面。因此,它使得开发和项目管理变得更有效率。

与 CMVC 相比,Rational Team Concert 引入了相似的概念以进行源控制,例如 构件缺陷,以及 特效(或者 事例)。但是,在 Rational Team Concert 中使用 流程 类似于 CMVC,意识到这一点很重要,但是前者拥有一些其他的功能。另外,Rational Team Concert 工作区可以作为您能查看和编辑构件的区域。

转移过程概述

尽管在 CMVC 和 Rational Team Concert 中进行配置管理,版本控制,变更控制,问题追踪以及数据存储都很复杂,但是幸运的是,我们不用为这点担心。我们只需要知道 CMVC 和 Rational Team Concert 数据格式之间的差异,并熟悉 CMVC 与 Rational Team Concert 客户端,然后通过调用 CMVC 客户端 APIs 以及 Jazz APIs 来将导入和导出的重复性步骤实现自动化。

在这种方法中,您要完全掌控转移过程。如果有什么错误发生的话,那么修复问题并从产生错误的地方重启是一件非常容易的事情。例如,如果当您导入源文件时,由于一些原因您不能访问远程 Rational Team Concert 服务器,那么找到最后成功导入的文件,然后从下一个源代码文件重启,就是安全的了。

一般有三个步骤,演示在图 1 之中:

  1. 准备
  2. 导出与导入
  3. 确认
图 1. 转移过程
具体的流程图
具体的流程图

前提条件

转移环境

CMVC 服务器版本是 is 5.0,而 Rational Team Concert 服务器版本是 2.0(Scrum Template 2.0)。

CMVC 以及 Rational Team Concert 库

转移用户访问

  • 对于 CMVC 5.0,用户需要特权去查看缺陷和特性,并提取出源代码文件。
  • 对于 Rational Team Concert 2.0 版本或者后续版本,用户应该拥有项目区域之中的 Scrum Master 角色权限。

本文的关注点

CMVC 与 Rational Team Concert 之间的目标并不是 100% 的匹配,这样我们就能够注意我们所处理的数据了。例如,我们可以决定只转移一些与项目有关的字段或者缺陷或特性,而不是所有的字段。

对于本文,我们关注的是调用 CMVC 客户端 APIs 和 Rational Team Concert 客户端 APIs,来按照自动的方式执行以下相关的步骤。

  • 导出缺陷或者特性(缺陷/特性)
  • 导出源代码和历史版本信息
  • 导入缺陷/特性
  • 导入源代码

准备转移过程

准备 Rational Team Concert 存储库

我们需要创建目标流程,工作区,构件,工作项类别,以及 Rational Team Concert 之中的通用属性(大多数的准备步骤都可以通过调用 Rational Team Concert APIs 完成,但是这并不是本文的关注重点)。为了完成该操作,我们需要完成以下的任务:

  1. 创建一个名为Create a stream named releaseA 的流程作为目标流程。
  2. 向 releaseA 添加两个构件: srcbuild 。构件基于 CMVC 构件名。
  3. 创建两个工作区, releaseAWorkSpace ,并将 releaseAWorkSpace 定位至 releaseA 流程。
  4. 添加工作项类别: srcbuild 。它们基于 CMVC 构件名。
  5. 添加通用属性, cmvc_name ,以存储 CMVC 缺陷和特性号码。通常来说,维持原始的 CMVC 缺陷和特性号码是一个不错的操作方式。我们可以通过向 Rational Team Concert 引入一个通用属性来完成该操作。为 缺陷任务 工作项向 Rational Team Concert 添加一个通用属性。通用属性名是 小字符串 类型。

对象映射规则

本文将会处理 CMVC 与 Rational Team Concert 对象映射规则。这些映射规则适用于大多数的情况,但是您可以尽可能地对项目使用它们。我们需要考虑对用户,缺陷和特性,属性与术语的映射,这样接下来的七个表就会涉及到它们中的每一个。

表 1. 用户映射
Rational Team Concert 用户CMVC 用户
电子邮件地址地址
名字名字
UserIduser_id

注意: User_id 在 CMVC 中用作标识符,并将会映射到 Rational Team Concert 中的 UserId。

表 2. 缺陷与特性映射
属性类型CMVC 缺陷或者特性Rational Team Concert 工作项类型:缺陷或者询问
缺陷属性名字cmvc_name(Rational Team Concert 端的通用属性)
compName字段
抽象总结
标记评论
remarks_seq描述
状态状态/解决方案
addDate创建日期
ownerName所有者
originName创建者
Attribute specific to Defect优先级优先级
强度强度

注意:cmvc_name 通用属性将用于存储 CMVC 缺陷或者特性号码。我们还可以映射其他感兴趣的属性。

表 3. 强度映射
CMVCRational Team Concert
1:关键性关键的
2:地位主要
3:错误正常
4:最低的最小
其他值未分类
表 4. 优先级映射
CMVCRational Team Concert
mustfix
候选的
延迟的
容易的中等
适度的中等
困难的
n/a未分配
表 5. 缺陷状态映射
CMVC 缺陷Rational Team Concert 工作项(缺陷)
开放的新的
处理中处理中
设计处理中
规模处理中
评审处理中
返回的已解决-为我服务
确认已解决-修复
取消确认的-为我服务
关闭的确认的-修复
转移的确认的-修复
表 6. 特性状态映射
CMVC 特性Rational Team Concert 工作项(任务)
开放的新的
处理中处理中
返回的延迟的
确认实施的
取消的无效
关闭的已完成
转移的完成的
设计处理中
规模处理中
评审处理中
表 7. 其他的概念映射
CMVCRational Team Concert
发布流程
构件构件
更改更改集

注意: CMVC 中的版本可以映射至 Rational Team Concert 项目之中的流程。

提示:

  • 请确定 Rational Team Concert SDK 的版本与 Rational Team Concert 服务器的版本都是相同的。否则,不可预料的例外情况也会发生。
  • Rational Team Concert SDK 中包含了源代码。查看源代码,是精确分析存在问题的一种不错的做法。从 Jazz.net 论坛寻求帮助与信息也会非常有用。您可以在 Jazz API 上找到关于 Jazz 开发维基的信息。
  • CMVC 客户端 APIs 的参数可能存在一些微小的差异,这取决于您所使用的具体 CMVC 版本。当然,在 下载 部分的导出代码中调整它们将是非常容易的。

使用 API 从 CMVC 中导出历史数据

CMVC Java 客户端 API 概述

CMVC Java™ 客户端 API 为客户端程序提供了一个 Java 界面,以访问 CMVC 服务器功能。现在所有的 CMVC 图形化用户界面客户端都基于该 API。现在开发员可以通过 API 来访问 CMVC。CMVC 客户端 API 设计提供了作为 命令 的交流单元。它们中的每一个都是已存在 CMVC 命令的同等物(例如 User -view 命令)。

在本部分中,我们将会简要查看一下 CMVC 命令,然后导出用户,缺陷和特性,以及带有历史版本的源文件。

  1. 调用 CMVC API Java Archive(JAR)文件以查看文件信息:
    1. 运行以下的命令,如图 2 所示,并登录到 CMVC 上:
C:\IBM\CMVCDC50>set_classpath=CMVC.jar
C:\IBM\CMVCDC50>java_com.ibm.sdwb.cmvc.client.api.SampleExe
  1. 然后调用如图 3 所示的 FileView 命令。我们可以得到从 CMVC GUI 客户端得到什么之类的信息。
图 2. 使用 CMVC API JAR 登录到 CMVC
命令行界面输出
命令行界面输出
图 3. 调用 CMVC API JAR 文件之中的 FileView 命令来查看文件信息
FileView 命令界面输出
FileView 命令界面输出
  1. 调用 Java 程序中的 CMVC 客户端 APIs 以查看文件信息。调用 Java 程序之中的 CMVC 客户端就像调用命令一样简单。

您只需要熟悉一下 CMVC 客户端 APIs 提供的一些 Java 类。命令子系统包含了以下这些类:

CommandFactory
这是 Command 对象的简单创建的机理。
Command
这是封装了与逻辑性的,或者高层次的 CMVC 命令相关数据的抽象类。
CommandResults
该类的实例封装了执行命令所生成的结果。
SessionData
该类的实例含有特定会话的数据,例如认证 CMVC 家族所需要的认证,以及默认的参数。
FamilyInfo
该类的实例封装了接触给定 CMVC 家族所需要的信息。

调用 CMVC FileView API 的核心 java 核心片段如代码清单 1 所示。您可以在 Download 部分中得到完整的代码。

清单 1. 调用 FileView 命令的核心 java 代码片段
// File –view
// get command
Command cmd = CommandFactory.getInstance().getCommand("FileView");
cmd.setFamilyInfo(familyInfo_);
cmd.setSessionData(sessionData_);

// set the command parameters
addParametersFileView(cmd, fileInfo.getFilepath());

// execute the command
CommandResults res = cmd.exec();

// analyze the essential information 
int rc = res.getReturnCode();
if (rc == CommandResults.SUCCESS) {
    logger.info("FileView:Succes");
    String pathname = res.getValue("FileView", "pathName");
    String globaltext = res.getValue("FileView", "null");
// analyze the key information: source code version, version owner and 
// the mapping defect/feature 
    getFileVersionInfo(fileInfo, pathname, globaltext, release);
// record the source code version, version owner and 
// the mapping defect/feature 
    fileWriter.write(fileInfo.getFilepath() + "\t" + fileInfo.getHistoryInfo() + "\r\n");
    fileWriter.flush();
} else {
    logger.info("FileView:failed");
    logger.error(res.getFailureMessages());
}

现在您已经对 CMVC API 使用有了一个大概的了解,所以现在我们接着去从 CMVC 中导出数据。

导出 CMVC 用户数据

在本例中,我们只会转移用户信息的三个字段:User ID,User Name 以及 Email。从 CMVC GUI 客户端或者命令那里直接导出这样的信息会非常简单。

  1. 我们定义了一个简单的用户数据格式:
    userid \t user name \t email
  2. 将导出的用户信息更改为如代码清单 2 所示的格式,并保存到一个名为 User.txt 的文本文件之中。例如:
    Jim Jhoon, Zonjjz@01.ibm.comjjz
清单 2. 导出的用户信息
Jim Jhoon, Zon	jjz@01.ibm.com	jjz
Hou liang, Zhen	zhl@01.ibm.com	zhl
Li Eric, Hans	heh@01.ibm.com	heh
Velu Lubin, Green	vlg@01.ibm.com	vlg
Kate Morton, David	kmd@01.ibm.com	kmd

导出 CMVC 缺陷或者特性

在导出具体的细节与特性之前,我们需要得到关于缺陷与特性号码的全部列表。使用 CMVC GUI 客户端或者命令可以轻松完成这一点。

  1. 将缺陷号码保存为一个名为 Def_no_list.txt 的文本文件,如代码清单 3 所示。
清单 3. 导出的缺陷号码列表
19484
19838
19840
19866
19905
19906
19921
19943
  1. 查询 CMVC GUI 客户中的特性列表,并将整个特性号码保存为一个文本文件, Fea_no_list.txt如代码清单 4 所示。
清单 4. 导出特性号码列表
20226
19428
19167
19405
21318
20286
  1. 在 Java 程序中导出缺陷或者具体的特性
  2. 对于 Def_no_list.txt 文件之中的每一个缺陷名,您可以调用 Java 程序之中的 DefectView 命令,以得到缺陷的具体信息,将其保存为自己的格式。
  3. 对于 Fea_no_list.txt 文件之中的每一个特性名,您可以调用 Java 程序之中的 FeatureView 命令,以得到特性的具体信息,并将其保存为自己的格式。您可以在 Download 部分中找到完整的代码。

图 4 演示了我们存储在文本文件之中的缺陷的具体内容。

图 4. 本文所用的缺陷或者特性存储格式
19167.txt 文件内容的屏幕截图
19167.txt 文件内容的屏幕截图

导出 CMVC 源代码

  1. 我们需要使用 CMVC GUI 客户或者命令,来为存储在 CMVC 中的所有文件生成源文件,然后将所有那些文件路径保存为文本文件,File_path_list.txt如代码清单 5 所示。
清单 5. 导出的文件路径列表
build/build.xml
build/make.cmd
src/lib/db2jcc.jar
src/lib/j2ee.jar
src/rad_echat/src/com/ibm/lenovo/database/driver/LenovoDBManager.java
src/rad_echat/src/com/ibm/lenovo/database/driver/TestDB.java
src/rad_echat/src/com/ibm/lenovo/database/driver/TestDBCreate.java
src/rad_echat/WebContent/chat/ChatView_01252007.jsp
src/rad_echat/WebContent/chat/ChatView_12112006.jsp
src/rad_echat/WebContent/chat/ChatView.jsp
  1. 导出 Java 程序之中的源代码:
    1. 对于 File_path_list.txt 文件中的每一个源代码,您可以调用 Java 程序之中的 FileView 命令,以得到历史版本信息。
    2. 对于文件的每一个版本,您可以调用 Java 程序之中的 FileExtract命令。
    3. 保存特定的历史版本源代码内容以及历史版本信息为自己的格式。查看 下载 部分以得到完整的代码。

清单 6 显示了历史版本信息存储格式。版本信息保存在 Path_historyver.txt 文件之中,当您将历史版本导入到 Rational Team Concert 时,将会使用到该文件。

清单 6. 导出的文件历史版本信息
build/build.xml	1.1,jyoungmn,19428;1.2,jyoungmn,19428;1.3,elubin,19405;1.4,
    jyoungmn,19405;1.5,dmorton,20286;1.6,dmorton,21318
build/make.cmd	1.1,jyoungmn,19167;1.2,jyoungmn,19428;1.3,jyoungmn,19405
src/lib/db2jcc.jar	1.1,eggerh,20279
src/lib/j2ee.jar	1.1,jyoungmn,19428
src/rad_echat/src/com/ibm/lenovo/database/driver/LenovoDBManager.java	1.1,ZSHAE,20226
src/rad_echat/src/com/ibm/lenovo/database/driver/TestDB.java	1.1,ZSHAE,20226
src/rad_echat/src/com/ibm/lenovo/database/driver/TestDBCreate.java	1.1,ZSHAE,20226
src/rad_echat/WebContent/chat/ChatView_01252007.jsp	1.1,ZSHAE,20226
src/rad_echat/WebContent/chat/ChatView_12112006.jsp	1.1,ZSHAE,20226
src/rad_echat/WebContent/chat/ChatView.jsp	1.1,ZSHAE,20226

导出历史版本信息的格式如下所示:

file full path\t version,owner,defect/feature;…

图 5 显示了源历史数据存储格式。例如:
build.xml@$1.1@$jyoungmn@$19428

图 5. 导出的源代码存储格式
build.xml 与 make.cmd 文件列表
build.xml 与 make.cmd 文件列表

对于所有的历史数据文件我们正在使用的是以下的命名习俗:
file name @$ version @$ owner @$ defect/feature

将历史数据导入到 Rational Team Concert

将用户导入到 Rational Team Concert

既然我们拥有所有需要导出的数据,那么我们就可以开始使用 User.txt 文件将用户导入到 Rational Team Concert 之中。如果只有少部分用户的话,手动导入它们也许会更快。否则,如有需要您可以使用 Jazz APIs 来完成操作。

将缺陷或者特性导入到 Rational Team Concert

接下来,我们将会处理缺陷和特性导入。

  1. 分析每一个导出的缺陷或者特性数据文件,以得到基于 Defects/Features Mapping 规则的基本属性。您可以决定只转移您所感兴趣的字段,而不是所有的字段。代码清单 7 只给出了核心导入 Java 代码。
清单 7. 导入缺陷或者特性的核心 Java 代码
private static class WorkItemInitialization extends WorkItemOperation {
    private WorkItemAttributes workItemAttr;
    public WorkItemInitialization(WorkItemAttributes workItemAttr) {
        super("Initializing Work Item");
        this.workItemAttr = workItemAttr;
    }

    @Override
protected void execute(WorkItemWorkingCopy workingCopy, 
		IProgressMonitor monitor) throws TeamRepositoryException {
        IWorkItem workItem= workingCopy.getWorkItem();

        // set the work item attribute one by one
         // …
    }
}

// work item creation
WorkItemInitialization operation = 
new WorkItemInitialization(WorkItemAttribute att);
IWorkItemHandle handle = operation.run(workItemTypeTask, null);
IWorkItem workItem = 
    auditableClient.resolveAuditable(handle, IWorkItem.FULL_PROFILE, null);

int def_fec_id_new = workItem.getId();
// record the return work item id and 
// the old CMVC defect/feature name mapping.  
sbFeatureMapping.append(def_fec_id + "\t" + def_fec_id_new + "\r\n");
  1. 调用 Rational Team Concert API 以创建工作项并记录返回的工作项 ID。您需要工作项 ID 以导入一个特定的代码版本。这就是说,我们将会使用为缺陷或者缺陷创建的工作项 ID 来检入每一个历史版本。
  2. 在那这后,将映射的工作项 ID 与 CMVC 缺陷号码写入到 Def_wrkitmID.txt 文件,如代码清单 8 所示。
清单 8. 缺陷名与工作项 ID 映射列表(范例)
20278	31
20279	32
20280	33

同样,将工作项 ID 与 CMVC 特性号码,映射到 Fea_wrkitmID.txt 文件,如代码清单 9 所示。

清单 9. 特性名与工作项 ID 映射列表
20226	34
19428	35
19167	36
19405	37
21318	38
20286	39

当您在导入源代码时,将会使用到这些 CMVC 缺陷或者特性号码以及 Rational Team Concert 工作项 ID 映射关系。与 CMVC 中缺陷或者特性相关的源代码文件,应该映射至 Rational Team Concert 之中的新工作项 ID。

将源代码导入到 Rational Team Concert

现在我们拥有了版本历史信息文件,Path_historyver.txt。在我们的版本历史信息之中,文件路径的第一部分就是构件名,例如“build”与“src”。

  1. 在 Rational Team Concert 工作区中创建并共享构件文件夹,如图 6 所示。
图 6. Rational Team Concert 中的共享构件文件夹
构建以及 src 构件的文件夹
构建以及 src 构件的文件夹
  1. 在 Java 程序中导入源代码历史:
    1. 在 Path_historyver.txt 文件查看每一个源代码文件以及历史版本,并创建映射新工作项 ID 的原始缺陷或者特性的更改集。
    2. 将源代码放到 Rational Team Concert 工作区之中,releaseAWorkSpace,然后将代码变更交付到 Rational Team Concert releaseA 流程之中。
    3. 当您在创建更改集时,在注释中添加 CMVC 版本信息是一个不错的操作方式。

清单 10 显示了核心的导入 Java 快照。

清单 10. 导入源代码的核心 Java 片段
IFileItem fileItem = null;
if(isNewFile()) {
    fileItem = (IFileItem) IFileItem.ITEM_TYPE.createItem();
} else {
    fileItem = (IFileItem) workspaceConnection.configuration(myComponent)
                     .fetchPartialItem(fileItem, null, monitor);
    fileItem = (IFileItem)fileItem.getWorkingCopy();
}
    
fileItem.setName(fileInfo.fileName);
fileItem.setParent(parentFolder);
                    
FileLineDelimiter delimiter = FileLineDelimiter.LINE_DELIMITER_NONE;
                    
IFileContent storedContent = contentManager.storeContent(
        IFileContent.ENCODING_US_ASCII, delimiter,
        new VersionedContentManagerByteArrayInputStreamPovider( 
             readFileToByteArray(fileInfo, version) ),
        null, monitor);

fileItem.setContentType(IFileItem.CONTENT_TYPE_TEXT);
fileItem.setContent(storedContent);
fileItem.setFileTimestamp(new Date());

IChangeSetHandle changeSetHandle = 
    workspaceConnection.createChangeSet(myComponent, "--" + version.toString(), 
        false, monitor);
    fileWorkItemmanager.createLink(workspace, changeSetHandle, 
        new IWorkItemHandle[]{handleWorkitem}, monitor);

// commit the change to workspace
workspaceConnection.commit(changeSetHandle, 
    Collections.singletonList(workspaceConnection.configurationOpFactory()
        .save(fileItem)), monitor);

// deliver the changes to the stream
IChangeHistorySyncReport sync = 
    workspaceConnection.compareTo(streamConnection, 
        WorkspaceComparisonFlags.CHANGE_SET_COMPARISON_ONLY,
            Collections.EMPTY_LIST, monitor); 

workspaceConnection.deliver(streamConnection, sync, Collections.EMPTY_LIST, 
    sync.outgoingChangeSets(myComponent), monitor);

确认转移结果

确认缺陷或者特性

图 7 显示了本文中范例的缺陷/特性转移结果。

图 7. 转移结果
6 列:选择,I,Status,P,S,Summary
6 列:选择,I,Status,P,S,Summary

确认源代码

图 8 显示了导入到 Rational Team Concert 中的所有代码文件。

图 8. 源文件转移结果
源文件显示了 releaseA 流程目录
源文件显示了 releaseA 流程目录

确认源代码历史

  1. 在releaseA(团队 1)流程层级结构来选择构建构件,然后右击并从下列菜单之中选择 Show — Repository Files。
  2. 选择您想要确认的文件(例如,构件构建的 build.xml 文件),然后右击并从下列菜单中选择 Show History。您就能够看到所有的历史版本了。

图 9 和 10 显示了源文件的历史版本。

图 9. 源文件历史版本转移结果,步骤 1
下列菜单中强调显示的 Show History
下列菜单中强调显示的 Show History
图 10. 源文件历史版本转移结果,步骤 2
Comment 列中的首行
Comment 列中的首行

现在您就能够将项目资源保存在原始的 SCM 系统之中,并充分享受 Rational Team Concert 带来的优势了。


下载资源


相关主题


评论

添加或订阅评论,请先登录注册

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=Rational
ArticleID=626091
ArticleTitle=使用 Jazz API 将历史性数据从 CMVC 转移至 Rational Team Concert 项目
publish-date=02092010