Tao-ReviewBoard V1.0.0使用手册 1
(C) 2010-2011 Alibaba Group Holding Limited.
|
|
|
6 在SVN资源历史记录中Post-Commit Request 8
7.1 强制刷新Groups、People、Repository的相关缓存 8
Tao-ReviewBoard V1.0.0使用手册
1 Tao-ReviewBoard插件解决的问题
为了使用ReviewBoard，用户不得不安装一系列软件，且安装过程非常繁琐和复杂；在使用ReviewBoard提交和更新Request时，用户必须使用复杂的命令来执行相关的操作。
Tao-ReviewBoard是在eclipse上开发的一款ReviewBoard插件。它很好的解决了安装和操作等问题，使reviewboard的使用更加方便。该插件目前支持ReviewBoard1.6及以上版本。现在，你已经不再需要在本地安装任何其它额外软件（甚至无需安装Subversion），也不再需要记住任何脚本和命令；在Eclipse中安装ReviewBoard插件后，提交和更新Request的操作将非常便捷，你只需要选中需要提交的代码或目录，然后右键Team进行相关操作即可完成Request的提交和更新（且支持Pre-Commit和Post-Commit方式）。Tao-ReviewBoard插件后续还将提供展示diff等诸多功能。
Tao-ReviewBoard插件的功能还在持续地丰富中。如果您在使用过程中有任何问题，或者有更好的建议，请联系淘宝：配置管理中心：千丫([email protected])。如果您希望与我们进行技术交流，可以联系淘宝：技术产品：智清([email protected])、银时([email protected])。Tao-ReviewBoard插件(开源版)的官方网址是：http://code.taobao.org/p/tao-reviewboard/wiki/index/。您可以在该网站了解Tao-ReviewBoard插件的最新动态、发行报告、FAQ、安装和使用说明等。Tao-ReviewBoard插件的源代码地址是：http://code.taobao.org/svn/tao-reviewboard/，或直接访问如下网址浏览源代码：http://code.taobao.org/p/tao-reviewboard/src/。感谢Markus Knittig，Tao-ReviewBoard插件中Core模块功能的部分代码借鉴并摘录了Markus Knittig的ereviewboard插件（官方网址：https://github.com/mknittig/ereviewboard）；感谢Subclipse项目团队，Tao-ReviewBoard插件目前暂时只支持Subclipse插件管理的Eclipse Project。
2 安装Tao-ReviewBoard插件
2.1 如何安装Tao-ReviewBoard插件
目前Tao-ReviewBoard暂时只支持Subclipse管理的Eclipse Project。我们欢迎大家参与进来支持其它方式的版本控制（如EGit、CVS等。扩展Tao-ReviewBoard的技术细节：您新开发的模块，例如CVS模块或EGit模块，通过使用扩展点：com.taobao.eclipse.plugin.reviewboard.core.clientRepositoryAwair获得IReviewboardClientRepository，进而操作ReviewBoard服务器）。
(1)由于现阶段我们只支持Subclipse，因此，需要使用Tao-ReviewBoard插件的完整功能，必须先安装Subclipse Eclipse插件，当前subclipse的最新版本是1.6.x。该项目主页是：http://subclipse.tigris.org，该插件的官方安装地址是：http://subclipse.tigris.org/update_1.6.x，请从Eclipse > Help > Install Software中直接安装。Subclipse是必选的安装组件。注意：一般来说，在Help > Install New Software页面，请不要勾选 Contact all update sites during install to find required software。如果勾选了该项，插件安装将是一个漫长的等待过程。如下图所示：
图：安装Subclipse
(2)安装完Subclipse Eclipse插件后，便可以安装Tao-ReviewBoard插件了。安装方法是（如下两种方法任选一种即可）:
(2.1)离线安装。您也可以将源代码目录的/updatesite/plugins目录下的所有jar文件拷贝至Eclipse的dropins目录（或plugins目录），然后重新启动Eclipse即可。或者参考http://code.taobao.org/p/tao-reviewboard/wiki/index/ 页面相关说明下载离线安装包。
(2.2)在线安装。我们推荐您使用在线安装方式，这将极大方便您今后的在线升级。官方安装地址：http://abs.taobao.org/updatesite/，请通过Eclipse的Help > Install New Software直接安装，安装前请先勾选需要安装的模块(请勾选所有模块)。注意：在Help > Install New Software页面，请不要勾选 Contact all update sites during install to find required software。如果勾选了该项，插件安装将是一个漫长的等待过程。
图：安装Tao-ReviewBoard
2.2 如何卸载Tao-ReviewBoard插件
(1)离线安装后的卸载方法：直接在Eclipse的dropins目录（或plugins目录）删除Tao-ReviewBoard插件的jar即可。
(2)在线安装后的卸载方法：卸载ReviewBoard插件的方法是：在Eclipse的Help->About Eclipse窗口中，点击Installation Details，打开Installed Software，找到Tao-ReviewBoard插件的各个模块，选中后，点击按钮Unintall，即可执行卸载。
3 配置ReviewBoard服务器并保存常用属性
使用ReviewBoard插件之前，您必须首先在首选项中配置服务器信息。
3.1 使用首选项配置服务器信息
可以通过"Windows->Preferences->Tao-ReviewBoard配置"打开首选项配置窗口对常用属性进行配置。
图：首选项处配置服务器并保存常用属性
参数含义：
Server：如果配置了多台ReviewBoard服务器，则需要在这里指定提交Request时具体会使用哪一台服务器。注意：Server的格式必须形如http://reviews.your-domain.org，以http或https开头。User ID和Password请使用你的域账号和密码。
Groups、Peoples：如果设置了这些项，那么提交和更新Request时，无需每次都输入相关项的值。
3.2 功能高级配置
可以通过"Windows->Preferences->Tao-ReviewBoard配置->功能高级配置"定制一些高级功能。
图：首选项处配置->功能高级设置
重置缓存信息：为优化用户体验，Groups、Users、Repository列表缓存到本地内存，以便提交或更新Request时，填写相关项时能快速给出智能提示。点击重置按钮后，将立刻同步服务器的数据到本地。
Post-commit模式自动获取start版本。插件会通过svn的路径和文件和目录的版本自动获取文件/目录的创建版本。
分支路径下post-commit模式自动获取start版本：如果svn路径中包含branches路径，则在post-commit模式，自动获取start版本为分支创建版本。
任意路径下post-commit模式自动获取start版本：svn路径中不包含branches的其他路径也可以使用这中模式，自动获取的start版本为所选文件中初始版本最低的版本号。需要指出的是这项勾选后，在post-commit模式打开提交页面时需要的时间会比较长。
Diff文件默认编码：默认是自动设置。一般来说无需改变该项，因为Tao-ReviewBoard插件会智能地判断代码的文件编码(GBK或UTF-8)。除非您某些极其特殊的情况下，插件智能判断文件编码失败或误判编码(主要体现在：diff文件是乱码)，您才需要手动指定diff文件编码。
3.2 页面显示高级配置
可以通过"Windows->Preferences->Tao-ReviewBoard配置->页面显示高级设置"定制一些高级功能。默认配置下，提交和更新Request时，不常用的功能，不将显示在提交或更新页面。但是，如果您在这里勾选了诸如Testing Done、Bug Closed等功能后，您会发现您的提交和更新页面多出了这些额外选项功能。
图：首选项处配置->页面显示高级设置
4 Pre-Commit方式提交或修改Request
图：Pre-commit方式提交或更新Request(页面显示高级配置中开启所有功能后的界面)
注：Tao-ReviewBoard插件已经支持多文件或文件夹跨越了多个不同Project的情况。如果是多Project提交，请确保这些项目的SVN Repository Root是同一个SVN地址。
在需要提交Request的代码处右键->Team->Pre-Commit Request To ReviewBoard，即可以Pre-Commit方式提交和修改Request。
可以指定比较版本（选填项）。未指定比较版本时，表示希望本地修改后的代码与SVN最新版本的代码比较；否则，表示希望本地修改后的代码与SVN仓库中的指定版本进行比较。
注意：Summary、People(即审核人)、Repositoy和The review request's description是必填项；多个people、group和BugClosed之间请用英文状态的','分隔;且BugClosed必须为数字！
用户还可以通过勾选Update Request来决定当前操作是全新提交Request还是修改Request；如果勾选了Update Request，即表示用户希望修改Request，此时必须输入需要修改的Request ID。
默认情况下将Publish Request，如果用户希望Save as Draft而不是Publish Request，请勾选Save as Draft(默认情况下界面上无此选项，除非已经通过首选项的页面高级配置功能自定需要该功能)。
此外，您在提交Request之前，可以使用代码比较功能，使用方法是：双击界面中待比较的文件的文件即可。
5 Post-Commit方式提交或修改Request
图：Post-commit方式提交或更新Request(页面显示高级配置中开启所有功能后的界面)
注：Tao-ReviewBoard插件已经支持多文件或文件夹跨越了多个不同Project的情况。如果是多Project提交，请确保这些项目的SVN Repository Root是同一个SVN地址。
在需要提交Request的代码处右键->Team->Post-Commit Request To ReviewBoard，即可以Post -Commit方式提交和修改Request。
注意：Summary、People(即审核人)、Repositoy和The review request's description是必填项；多个people、group和BugClosed之间请用英文状态的','分隔;且BugClosed必须为数字！
用户还可以通过勾选Update Request来决定当前操作是全新提交Request还是修改Request；如果勾选了Update Request，即表示用户希望修改Request，此时必须输入需要修改的Request ID。
默认情况下将Publish Request，如果用户希望Save as Draft而不是Publish Request，请勾选Save as Draft(默认情况下界面上无此选项，除非已经通过首选项的页面高级配置功能自定需要该功能)。
Post-Commit方式时，需要指定Start和Stop版本号。如果选中了多个文件和文件夹，插件会为所有选中的文件和文件夹生成diff文件并上传到ReviewBoard服务器。
Tao-ReviewBoard插件在处理用户手工填写的Start和Stop版本号时，插件的容错性非常智能化；如果填写的版本号过高或过低，插件将自动查找正确的版本号。
此外，您在提交Request之前，可以使用代码比较功能，使用方法是：双击界面中待比较的文件的文件即可。（目前暂时只支持文件比较，不支持文件夹比较功能）。
6 在SVN资源历史记录中Post-Commit Request
更多的时候，你可能希望在SVN资源历史记录处以Post-Commit方式提交或修改Request。具体方法是：
选中需要操作的代码或代码目录，右键Team->显示资源历史记录，即出现代码修改的历史日志记录。
或：直接从Eclipse的SVN资源库中打开的历史记录，也同样支持 Post-Commit Request。
选中需要对比的两个版本号（也可以只选中一个版本号，待弹出提交界面后，手动修改Start和Stop版本号），即可以使用Post-Commit的方式提交或修改Request。如下图所示：
图：资源历史记录中Post-commit方式提交或更新Request
7 其它技巧
7.1 强制刷新Groups、People、Repository的相关缓存
为了优化用户体验， Tao-ReviewBoard插件将ReviewBoard服务端的Groups、Users和Repository信息保存在本地缓存中。如果你修改了ReviewBoard服务器上的相关配置，例如新增了一个Group、修改了Repository对应的SVN地址。如果提交时提示找不到该Group或Repository，您可以用如下方式立即强制刷新本地缓存（或重新启动Eclipse，或等待Tao-ReviewBoard在若干分钟后自动刷新Cache）：
"Windows->Preferences->Tao-ReviewBoard配置->功能高级配置"打开首选项配置窗口，点击"重置"按钮即可重置配置的所有服务器的缓存信息。
8 常见问题答疑
1.安装Tao-ReviewBoard插件后，右键Project Properties，找不到相应的菜单项，这是怎么回事？
非Subclipse关联的Project不会出现Tao-ReviewBoard的任何菜单。如果右键后，找不到功能菜单，可能是因为您的项目不是SVN检出的项目。
如果您是以离线方式安装的Tao-ReviewBoard插件，且您确认你的项目就是Subclipse关联的Project，但是右键后，相关菜单仍未出现。那么，请关掉您的Eclipse删掉eclipse目录下的configuration/org.eclipse.update目录，然后重新启动Eclipse即可。
2.配置信息填写正确，点击apply提示用户名密码错误。
检查插件版本与reviewboard版本是否匹配。Tao-ReviewBoard V1.0.0是基于reviewboard 1.6版本的接口开发的，支持1.6及以上版本的reviewboard服务器。对于低版本的服务器我们不能保证提供稳定功能。
3.无法提交request，提交后报异常，或者diff有乱码无法正常展示？
以我们的经验，提交Review后插件提示错误信息；或者并未提示错误信息，但是浏览diff时显示乱码，一般来说，是由于如下原因中的某种或某几种：
3.1.请确认您在首选项中正确地配置了服务器信息、用户名和密码；且您确保ReviewBoard服务器正在正常运行。
3.2.请先检查您的代码所在的SVN路径或Eclipse的当前workspace、project所在目录是否存在中文。如果存在，请更改为英文。
3.3.diff文件乱码或不可识别问题：如果您选中的多个目录或多个文件包含有不同编码格式的文件(例如既有UTF-8文件，又有GBK文件)，那么乱码问题将始终无法避免（由于一次提交最终只会产生一个diff文件。可想而知，如果Tao-ReviewBoard插件以GBK编码产生diff文件，那些UTF-8的文件的diff展示必将是乱码；反之亦然）；Tao-ReviewBoard插件所能做的，就是弹出窗口，提示您可能存在该风险，并询问您是否继续。
3.4. 之前还发现部分用户有这种不规范的操作：用户从其它项目拷贝一个目录（例如名为tempfolder的目录）到当前工程，而拷贝的时候，顺便把tempfolder目录在其它项目的SVN属性给拷贝过来了（tempfolder的目录下可能有个.svn的隐藏目录）。显然，这种情况下SVN属性是错误的。这种情况下，diff自然无法正常查看；而且，这种错乱的SVN信息会使得用户很纠结，因为用户在提交代码时，会发现该目录下的任何代码无论如何都无法正常提交到SVN服务器。
3.5.如果还是出现diff无法正常展示，请通过首选项指定本次提交的编码格式（假设你已经明确知道本次提交文件的编码格式）。
3.6.如果还是存在乱码，请打开Eclipse的window->preferences->Team->SVN；更换一个SVN接口(SVNKit或JavaHL)试下。推荐使用JavaHL接口。如下图：
3.7．最后一种情况：从web界面下载您的diff文件，您发现该diff文件不是乱码，但页面展示时是乱码，请联系ReviewBoard服务端维护人员，修改在ReviewBorad服务器端您的代码所对应的Repository的Encoding(The encoding used for files in this repository. This is an advanced setting and should only be used if you're sure you need it)即可。