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”。