软件配置管理STARTEAM HOWTO:
7. Starteam Howto
针对 STARTEAM，写了如下 HOWTO。原因是图形界面的操作固然尤其方便性，但也随处埋藏着地雷。
例如：权限设置不当，任何人可以选择工程的根目录，按一下DEL键，只有一次确认机会，便会在不到一秒种的时间，删除整个工程所有文件。如果这时不知所措，重新再次重建整个工程，比如重新 checkin 整个工程的 5,000 个文件，则服务器中的文件个数翻倍。这些文件作为新文件，不但你为找不回Commit LOG 而头大，管理员总有一天为服务器存储空间头大。
7.1. Server Configuration
7.1.1. 用户角度
在使用 starteam 客户端连接服务器前，首先要设置服务器的IP地址，端口号等参数，以建立连接starteam服务器的Profile。这可以称为用户眼中的Server Configuration。
用图形界面的 starteam 客户端，如下方式设置：
-
Project-->Open-->Add Server
-
设置服务器名，IP地址，协议（TCP/IP Sockets），端口（49201），加密（选择任意一种加密方式）。
命令行 starteam ，请用我们自己封装的 Wrapper: "st" 。
obsd99:/home/jiangxin/work/src/project/main>st config
StarTeam Configuration
Original starteam server is 10.1.1.60
new server:[10.1.1.60]
Original starteam server port is 49201
new server port:[49201]
original username is jiangxin
new username:[jiangxin]
Password:[********]
Original checkout project is project
Project you want to checkout:[project]
Original checkout view is ("/" means root view)
View you want to checkout:[]
Original checkout folder is Development ("/" means root folder)
Folder you want to checkout:[Development]
Working dir is /usr/home/jiangxin/work/src/project/main
Your working directory:[/usr/home/jiangxin/work/src/project/main]
Sticky tag base on date : ("/" means not exist)
Date:[]
Sticky tag base on label : ("/" means not exist)
Label:[]
Sticky tag base on promotion-state : ("/" means not exist)
Promotion-state:[]
|
Server Configuration的配置保存在工作目录中；用户口令加密保存在用户主目录的文件 .stpass 中。
7.1.2. 管理员角度
-
一个服务器配置（Server Configuration），作为一个独立的服务运行，有独立的用户数据库，独立的版本控制文件仓库（Repository），独立的一个数据库来支持。
-
一台服务器上可以运行多个不同的STARTEAM服务器配置，不同的SERVER CONFIGURATION需要分配不同的端口设置。
-
一个服务器配置内可以运行多个工程（PROJECT），一个Project中可以有多个视图（View），视图中有目录、文件、Change Request等元素组成。
-
一个服务器配置中的文件等元素可以在工程之间，视图之间共享（类似于拷贝的动作）；但是元素不能跨服务器配置共享。
-
文件结构：
配置文件
Configuration\server.scg
Configuration\server.cph
-
数据库文件
Database\StarTeamDB.mdb (Assuming Access database)
-
数据仓库
版本控制文件仓库（Repository）：Vault/Archive/ ；版本控制文件存储在该目录中，其中没有子目录，文件名以流水号依次排列；每个文件控制一个分支的所有版本文件的控制，类似于CVS的版本控制文件，但不同之处是该文件包含二进制的头尾，如果文件分支，CVS仍由一个文件来控制，而STARTEAM 则形成一个新的文件；CVS的TAG包含在文件上，即如果对文件加TAG，文件被更新，而 STARTEAM的LABEL（相当于CVS的TAG）不包含在文件中，而是存储在数据库中。
-
Cache
Cache文件夹是为了加速文件CHECKOUT。当一个文件被CHECKOUT，便在该目录建立 Cache，文件名结构为："文件名.版本号"。
-
其他
包括LOG，Attachments（change request, Topic等的附件文件）
7.3. View
-
通过 Project-->Open 来打开某一工程，会显示视图列表。视图间的关系通过一个树图表示出来。根视图通常作为工程的缺省视图，直接选择某工程，和选择缺省视图的效果一致；
-
根视图通常表示目前正在开发的版本；而分支视图表示维护的旧代码分支，或者功能独立的代码分支；
-
视图是主要用途是管理分支，即将一个分支作为一个独立的视图；当然也可以对不同用户建立视图，但是通过对目录的权限控制来实现不同用户使用同一个视图更好；
-
如果对视图中不同目录分别设置权限，则用户查看该视图，只能看到具有权限的目录。
-
label只在同一个视图中起作用，且View Label, Build Label, Promotion State 作用于一个视图中所有文件；
-
由于Change Request需要用到Build Label，测试人员用到Promotion State，因此需要在同一个视图内存放程序目录，Change Request目录，测试人员目录等；但文档具有相对独立性，建议单独建立工程，再共享到其他工程和视图中。
7.4. Branch
7.4.1. STARTEAM和CVS的分支不同点
-
CVS基于文件管理，不同分支的同一文件，即使内容不同，也都体现在同一个文件中； STARTEAM 建立分支是基于工程和数据库，两个分支的文件可以指到一个相同的物理文件，也可以使不同的物理文件，这样两个分支的文件可以同步变化（float branch），也可以分别独立控制（fixed branch）；
-
CVS分支用tag来管理，不同分支用 rtag/tag -b 来建立，并且不同分支打的分支tag或tag，可以被其他分支看到。 STARTEAM 的分支不通过建立标签实现，而是生成另外的一套数据库。
-
STARTEAM建立分支的方式：
-
同一视图的不同目录
另外建立一个目录作为分支的根目录，用ctrl+Drag将预建立分支的版本在该目录建立共享，再选择BehavioràBranch on change；则在这些文件修改并checkin 时，会建立新文件而分支；也可以为方法1新创建的分支目录来建立视图来方便管理。
-
不同的视图（建立分支视图）
创建分支视图，在创建过程中选择Permit items to branch within this view，来创建分支。分支视图的好处是，有自己独立的lable(tag)命名空间，不象CVS 只有一个TAG命名空间。
-
推荐使用分支视图方式。
-
-
CVS、STARTEAM都可以实现分支和主线和合并。
CVS 命令行功能强大，可以通过命令行完成分支的管理；而 starteam 对视图的管理只能通过图形界面实现。
7.4.2. 建立分支注意事项
7.4.2.1. 通过分支视图建立
-
建立新视图，在步骤一，选择文件分支，如图
建立分支视图步骤一
-
在步骤五，注意"Floating Configuration"和"Configure as ..."的区别
建立分支视图步骤五
一般情况下，请选择"Configure as ..."，这样当建立完成后，程序即刻分支，否则选择"Floating Configuration"，子视图在没做修改前，一直和父视图同步，称为 "Variant View"。
如果选择了"Floating Configuration"，可以通过将分支视图的所有文件强制 Check In，即可。
-
判断建立好的视图是否为分支视图，查看视图的属性。
视图的属性
7.5. Label
STARTEAM的标签（LABEL）主要用来记录事件，如里程碑，和代码分支没有必然的联系；而 CVS 的分支必须依靠 TAG 来完成。
CVS 的TAG是记录在文件中，建立 tag ，耗时；Starteam 的 LABEL是建立在数据库基础上的，建立 label，属于毫秒及的动作。
Starteam 地 LABEL 是建立在视图中，文件和视图脱离关系，该文件上的 label 失去。
如何使用LABEL管理项目的示例，参见：http://www.fox.se/english/starteam/best_practices/starteam_best_practices.htm，提供了STARTEAM利用LABEL协同工作的范例，这些工作有些是CVS很难做到的。
下面具体介绍 label 的几个不同的变种： View Label, Build Label, Promotion State, Revision Label。
7.5.1. View Label
-
View Label 针对一个View中所有文件，可以用来记录项目的里程碑。
-
View Label非常灵活，可以将后来新增加的文件加入到View Label中。
-
文件移到到其他视图和文件删除对view label 有不同影响：移出文件的 View Label会自动去掉，并且历史视图，该文件也不存在了，因为文件被移动了。删除的文件则不然，仍可以通过历史被访问到，并且删除前的文件仍然具有该 View Label
7.5.2. Build label
-
在创建View Label中有"Use as Build Label"的选项，默认创建的View Label 就是Build Label。
-
Build Label基本上等同于View Label，除了Build Label 在Change Request的工作流程中会被引用到。Build Label可以用来帮助测试人员了解Bug在哪一个 Build Label中被解决了。
7.5.3. Promotion state
-
Promotion State 可以看作是是浮动的View Label， View Label 的标签；
-
通常要建立的 Promotion State 有： Release, Beta Test, Alpha Test, ...。并且要按照顺序建立，这样可以通过提升，将 Beta Test 对应的 Build Label，提升为 Release，即用 Release 来指向 Beta Test 的Label。
-
建立在View Label基础之上，为编译 Checkout 代码，提供一个一致的Label。可以方便地建立 Nightly Build 系统。
7.6. 目录划分
表格 2. 项目工程目录结构
| 目录 | 说明 | 权限 |
|---|---|---|
| Development | 程序源码，及帮助 | 组成员完全权限 |
| Defect | 用于记录缺陷控制的目录 | 组成员控制changRequest完全权限；所有人具有添加修改changeRequest权限 |
| Document | 项目文档 | 组成员完全权限；文档工程师完全权限。（现已废弃不用） |
| ProjectManagement | 项目范围控制，时间控制等 | 组成员读权限；项目经理完全权限 |
 |
以上各个目录，只有项目管理人员和系统管理员具有修改安全设置权限。 |
7.6.1. 源码的版本控制
-
Development目录下建立各个相关模块目录；
-
模块的目录组织结构应该和 checkout 到本地的编译代码目录结构一致。
-
注意二进制文件尽量不要放在 Starteam 中，而改用其它方式（如文件服务器），来进行存储！
CWAP 1.1分支视图目录结构图
7.7. 删除和反删除
删除和反删除文件是 Starteam 和 CVS 最大的不同点之一。如果处理不好，虽然不会造成信息丢失，但处理方式不擅，将给 starteam 服务器端引入过多的数字垃圾。
原则是：
-
添加文件慎重
添加文件前，一定要将临时文件和二进制文件（编译过程的目标文件，可执行文件等）排除在外，以免引入数据垃圾。因为 Starteam 很难将文件彻底从服务器端删除。
-
反删除文件照章办事
反删除文件，按照本文档的步骤执行。严禁通过重新添加方式，反删除，否则同样引入数据垃圾！
7.7.1. Starteam文件存放机理
STARTEAM以数据库为核心，是面向工程的管理方式。版本控制文件的文件名由数据库管理，文件名不过是"指针"。方便文件在一个工程甚至同一个 Server Configuration的不同工程中的共享，以及任意移动和组织。
CVS,Perforce以文件为核心，即面向文件的管理方式，文件可以方便的重新组合以及移植。原子化的Check In、二进制文件的版本控制是更Perforce的优势。但是缺点是很难完成一个工程中，文件的移动及文件改名给前后不同版本/分支带来问题；不当处理或者丢掉以前版本控制中的文件部署，或者增加由于文件冗余增加占用空间。
STARTEAM的不利因素是很难将一个工程或者Server Configure中的文件分离、组合、单独移植。其数据仓库 Repository像一个黑盒子，所有Project的所有版本控制文件，都放在同一个目录下（Vault/Archive目录下，这是starteam的不足）。目前缺乏良好的文件管理工具，是一个缺憾。
Starteam 一旦对文件进行版本控制，就丢入 Repository 目录中，很难在从中删除。这应当看作是其最大的 BUG。
7.7.2. 删除
无论文件从哪个视图（根view，子view）添加目录和文件到starteam，在该view下显示的文件夹和文件只不过是Vault/Archive目录下文件（以流水号作为文件名），在数据库（starteam的管理核心）中的一个"指针"，删除文件，不过是删除了"指针"，虽然没有真正删除文件，但是如果数据库中的所有关于某个文件的 "指针"都删除，文件只能通过历史来查看。但可以通过适当方法，通过历史的 "指针"重新找回版本控制。
7.8. 文件服务器和个人版本控制
starteam的使用，并不能取代现有文件服务器的功能，因为starteam的版本控制系统文件存储的特殊性。
starteam所有版本控制文件存贮在同一个目录下（Vault/Archive），没有任何子目录，文件名按照流水号递增，并且一个文件一旦进入版本控制，一直不会删除。
优点是可以方便文件的改名，重新的目录组织，而不是象CVS那样很难修改文件名。
缺点是无法控制文件存储方式和存储量，对二进制（包括WORD文档）的版本控制管理不好。因此一些工具及不需要版本控制的文件尽量仍放在文件服务器上。
starteam不是百宝箱，但更不能成为垃圾桶。如对一些不需要纳入工程，统一管理的，但仍需要版本控制的文件，建议使用CVS，进行个人维护。CVS有Unix和NT版本的SERVER，都很好用。
7.9. 客户端设置
-
换行符转换（CRLF->LF）
选择根目录或者需要单独设置的目录，选择菜单： Folder->Properties->Files->Eol Conversion，如图：
-
Workstation Options
选择 Tools->Workstation Options
-
Workstation Options: Workspace
-
在目录和Change Request中切换过程中，不改变文件夹
-
改变路径时，取消文件递归，避免打开文件递归，切换到文件较多的目录，影响响应速度
-
切换文件夹，保持对filter的修改
-
对多用户环境（如管理员）有帮助
-
-
Workstation Options: Files
-
将文件的最后修改时间作为检出时间（强力推荐），否则为当前时间
-
只在必要时，打开Merge程序解决冲突
-
设置默认文字处理程序，如: Ultraedit
-
吴昭坚报告说：“如果把 Optimize for slow connection 的勾给选上了，结果在check out文件时极慢（check 一个文件要差不多1分钟）”
如果网络速度足够快，就把这个钩钩去掉，以减轻服务器和客户端的计算负担。吴昭坚还报告说 st 命令行亦会变慢，我觉得 st 变慢，是由于 ip 反向解析造成的超时，可以在 hosts 中加上 starteam 服务器的相关地址映射（如： 10.0.0.60 starteam），更极端的做法是删除 /etc/resolv.conf。
-
-
修改口令和个人信息
选择 Tools->Server Administration->My Account
7.11. Starteam CLI Wrapper
stcmd 是 starteam 的命令行工具，基于 java。因此运行 stcmd，首先需要建立 java 环境。对于 OpenBSD 系统，要Enable FreeBSD Compatible，再安装 Jave 虚拟机。
Starteam 的功能远远弱于其图形界面，而且命令行参数复杂，难于使用。我们用 SHELL 包装了一层：“st”，采用类似 CVS 的命令行。
理解 .starteam.ini
# .starteam.ini 通过命令 st config 生成 # StarTeam Configuration: /usr/project/branch2/release/.starteam.ini STUSER="releng" STPASSWDFILE="/project/.relfw.passwd" STSERVER="10.1.1.60" STPORT="49201" STWORKROOT="/usr/project/branch2/release" STPROJECT="project" STVIEW="branch_2_0" STFOLDER="" STCFGD="" STCFGL="" STCFGP="release" |
st 的参数及使用方法
StarTeam command line emulator, $Revision: 1.50 $, by YZW,JX
Usage: st [st_options] [st_command] [command_options] [command_args]
st
The name of the starteam wrapper
st_options
Some options that affect all sub-command of st.
st_command
One of several different sub-commands.
command_options
Options that are specific for the command.
command_args
Arguments to the commands.
Global options
=============================================
-h help
-V show version
-r readonly
-w readwrite
-v verbose, show version info. (--nv : no verbose)
-z compress during tranfer. (--nz : not compress)
-q a bit quiet mode. only show difference.
-qq more quiet mode. more quiet then -q.
(not show status "Not In View" and folder info)
-Q most quiet mode. output nothing.
(--nq: not quiet is default)
--eol set eol(symbol of end-of-line) to platform specific.
CR on unix, CR/LF on windows. (--neol : leave eol aside)
-I Interactive mode. ( --nI / --batch : Batch mode.)
-S / -s
Stop on error./ No Stop.
--exitcode
On Error return 1, success return 0.
Conflict with -q and -qq
Command Options
=============================================
-f Force. Force starteam to ci/co a new revision even if you
haven't made any changes to the file. _'
-l Local; run only in current working directory, rather than
recursing through subdirectories.
-R Process directories recursively.
-m message
Use message as log information, instead of invoking an editor.
-D date spec
Use the most recent revision no later than date spec.
date spec is a single argument, a date description specifying
a date in the past.
--lock / --unlock
Lock files./Unlock files.
-r tag
Use the revision specified by the tag argument instead of the
default head revision.
Commands
=============================================
help
----------------------------------------
Syntax: st help
Show this screen.
config
----------------------------------------
Syntax: st config
Maybe the first command you run. Configure INI file.
Truth behind "st config". Only for smart boys/girls:
After running this configuration, a config file, .starteam.ini
will be created under current directory.
There several KeyValue pairs.
STUSER : login name for starteam user
STSERVER: ip address of starteam server
STPORT : tcp port of starteam server
STPROJECT: project name you want to check in/out
STVIEW : view name you want to check in/out
STFOLDER: folder name of the view you want to check
STCFGD : check out base on Date.
Date format:
"12/29/97 10:52 AM"
"29-Dec-97 10:52:00 AM"
"December 29, 1997 10:52:00 AM PST"
"Monday, December 29, 1997 10:52:00
oclock AM PST"
STCFGL : check out base on Label
STCFGP : check out base on Promotion State
STWORKROOT: the root of your working dir
default
----------------------------------------
Syntax: st default
Show default params
add
----------------------------------------
Syntax: st [global_opts] add [--lock|--unlock|--nelock] [-m "message"]
[--vl "label"] [files...]
Add files to version control
import (add-folder)
----------------------------------------
Syntax: st [global_opts] import [--ex "excludeType"][--exlist "fileMask" |
--exfile "fileName"] [foldername...]
Add directory.
ci (commit / checkin)
----------------------------------------
Syntax: st [global_opts] ci [--filter ...] [--lock|--unlock] [-m "comment"]
[--force] [--necessary] <files...>
Check in files from local to server.
co (checkout / update / up)
----------------------------------------
Syntax: st [global_opts] co [--lock|--unlock] [-r revision] [--nessary]
[--touch][--merge [--dryrun|--alwaysprompt|--neverprompt|
--conflictprompt] <files...>
Check out files from server to local.
checkdir (cd)
----------------------------------------
Syntax: st [global_opts] cd <directory...>
Check out the Directory structure, but no files.
diff
----------------------------------------
Syntax: st [global_opts] diff [-r revision] [--filter ...] <files...>
differ.
list
----------------------------------------
Syntax: st list <files...>
List files. Show file size and status.
log (history)
----------------------------------------
Syntax: st [global_opts] diff [-r revision] [--filter ...] <files...>
Show logs.
status
----------------------------------------
Syntax: st status
Update file status.
tag (lable / apply-label)
----------------------------------------
Syntax: st [global_opts] tag [--filter "fileStatus"]
[--vl "labelName"|--vd "asOfDate"|--vn revision]
--label "labelName" [files...]
Apply a already exist lable to file(s).
describe (dsc)
----------------------------------------
Syntax: st dsc -m "message" <files>
Change the desciption of file(s).
release (remove /rm)
----------------------------------------
Syntax: st [global_opts] rm [--filter ...] <files...>
Remove Local files.
remove-repos (rm-repos)
----------------------------------------
Syntax: st [global_opts] rm-repos [--filter ...] <files...>
Remove files from version control.
undelete
----------------------------------------
Syntax: st undelete
Only be can be done in GUI mode.
lock
----------------------------------------
Syntax: st lock
Lock and Unlock files.
mk-build-label
----------------------------------------
Syntax: st mk-build-label
Make a build label.
mk-revision-label
----------------------------------------
Syntax: st mk-revision-label
Make a revision label.
mk-view-label
----------------------------------------
Syntax: st mk-view-label
Make a view label.
admin
----------------------------------------
Syntax: st admin --server <server> --pwdfile <pwdfile> [lock|unlock]
Server admistration command. Lock/Unlock server.
update this script and other scripts:
st getst
st putst
Filters:
C: Current
G: Merge
I: Missing
M: Modified
N: Not in view
O: Out Of Date
U: Unknown
"st getst" : Update your st immediately.
|
7.12. StarTeam 与 常用开发工具整合
StarTeam 可以和如下开发工具整合
-
Starbase CaliberRM 4.0
-
Starbase CodeWright 7.0
-
Microsoft Visual Studio .NET (Visual Basic, C++ and C# projects)
-
Microsoft Visual C++ 6.0
-
Microsoft Visual Basic 6.0
-
IBM WebSphere Studio Workbench 4.0.0 and 4.0.3
-
Sybase PowerBuilder 7.0 and 8.0
-
Rational Rose 2001 and 2002
-
Embarcadero Describe 5.5 and 5.8
-
Microsoft Access 2000 and 2002
-
Borland JBuilder 6.0 and 7
-
Borland Delphi 5.0 and 6.0
-
Borland C++Builder 5 and 6
-
Microsoft Visual InterDev 6.0
-
Oracle Developer 2000 and 6
-
Microsoft Project 98, 2000 and 2002
Starteam 和这些开发工具的整合需要安装 “StarTeam Integration”，如对于和 Microsoft Visual C++ 整合，需要安装 “StarTeam Microsoft SCC Integration”。
浙公网安备 33010602011771号