post-review
概述
post-review工具用于快速提交Review Request，适用于Windows、Linux和MacOS X平台，可以简化Review Request的创建和更新。本工具可以根据当前的源代码目录的变更情况，自动生成Diff文件，更新已有的Review Request，比通过Web UI提交Review Request节省不少时间，也减少可能出现的问题，对于某些特定的代码版本库，如Perforce，则是必须使用的提交工具。
post-review是RBTools包的一部分，可以通过命令直接在线安装和升级：
easy_install _U RBTools
创建和更新Review Request
根据不同的版本库类型，使用post-review时要求有变更集号（如Perforce），或者当前源代码目录中的变更（如Subversion），最终的结果是post-review生成一个Diff文件，并将它提交到Review Board服务器上，同时生成一个Review Request初稿，在补充完整其余信息后，Review Request可以正式提交。
当然，post-review工具也提供了多种参数，允许在命令执行时，即补充完整所有的信息，同时正式发布到Review Board服务器上，生成一个新的Review Request。
在提交新的Review Request或更新现有的Review Request之后，post-review会显示该Review Request的URL，如果使用-o参数，则会调用浏览器直接打开URL显示Review Request。
由于不同的版本库类型对post-review的使用要求不同，而我们公司目前使用了SVN、GIT和ClearCase，因此下面只针对这些版本库类型的post-review进行详细说明。
CVS/Subversion
对于CVS和SVN，使用工作拷贝中未提交的变更来生成Review Request，对这些变更进行评审。要对这些未提交的变更提交新的Review Request，只需要运行命令即可：
post-review
在不跟任何参数的情况下使用post-review命令，会生成diff文件，并提交一个新的Review Request。如果要工作拷贝中的变更，更新现有的Review Request，则需要使用-r参数，其后跟要更新的Review Request的ID号，如：
post-review –r 42
即用新的变更更新已有的Review Request #42。
如果要提交特定的文件，而不包括其他变更的未提交文件，则可以在命令中包括这些需要提交的文件，如：
post-review src/rrdm.c inc/signal.h
分布式版本控制系统
如果使用分布式版本控制系统，如GIT或Mercurial，那么你所修改的代码有可能存在于ReviewBoard配置的版本库尚不能访问的分支上，在这种情况下，就需要利用post-review的父diff文件支持。
所谓的父diff，是指某些ReviewBoard可以访问的已知上游版本和你当前分支的父分支之间的diff，它用于为你当前工作分支的diff提供工作基线。
以Git为例说明，你可能在topicB分支上开发，该分支有如图所示的上游分支：
o master
\
o---o topicA
\
o---o topicB
如果需要上传topicA和topicB之间的所有差异，则必须让post-review创建在master和topicA之间的差异，也就是父diff。
可以使用带有分支名称的--parent参数来实现，如，在本例中，只需要输入命令：
post-review --parent=topicA
则会自动创建master和topicA之间的父diff，以及topicA和topicB之间的正常diff。父diff中的差异在diff viewer中不会作为变更出现，也就是说，你只会看到在topicB中的修改。
注意：
这种方式目前只适用于GIT，并且假定master代表ReviewBoard可以访问的上游版本，这通常意味着master和origin应该指向同一个版本，以后的ReviewBoard版本处理方式会更灵活。
ClearCase
post-review同样支持对ClearCase代码评审，如果需要将当前视图中checkout的文件提交评审，只需要在当前视图目录下运行命令：
post-review
如果使用变更集，例如使用ClearCase/ClearQuest集成，也可以用--revision-range参数传递变更集，基于当前VOB的UUID或名称决定版本库名称。
post-review --revision-range="/vobs/proj/file.c@@/main/0:/vobs/proj/file.c@@/main/1"
post-commit review的另一种方式是用--tracking参数发送分支上的变更：
post-review --tracking my_dev_branch
注意：
post-review试着根据VOB的UUID匹配ReviewBoard配置的版本库，如果有问题，就是用VOB的名称匹配版本库。需要记住，使用.reviewboardrc文件或-repository-url参数可以取代此匹配版本库的方式。
Post commit代码
一般情况，post-review假定你需要提交的是尚未提交到版本库中的代码，也就是pre-commit review。但有时候也需要对已经提交到版本库中的代码进行评审创建，如在某个测试分支上的修改，这称为post-commit review。
post-commit review需要用--revision-range参数，该参数可以基于已提交版本创建diff。如果需要的话，可以用单个Review Request显示标识整个分支所有修改的diff。
使用也很简单，只需要输入命令：
post-review --revision-range=STARTREV:STOPREV
其中STARTREV是版本范围的起始版本，STOPREV是终止版本（diff包含该版本的修改）。如果只需要提交单个版本的修改，可以输入命令：
post-review --revision-range=REVISION
更新已有的Review Request，如前所述，使用-r参数指定该Review Request的ID号。
提交现有diff
post-review命令会自动根据版本库类型创建diff，如果想提交现有diff，可以使用--diff-filename参数指定diff的路径。如：
post-review --diff-filename=mycode.diff
也可以使用特定的值-，将diff管道标准输入中：
cat mycode.diff | post-review --diff-filename=-
自动post-review
post-review可以代表用户自动提交Review Request。通过特定的ReviewBoard用户和--submit-as参数，版本库的post-commit脚本可用来自动创建或更新Review Request。
先注册新用户，该用户限于脚本使用，有特殊的权限，密码需要特别的保密。需要授予该用户“Can submit as user”和“Can edit review request”权限，这可以确保该用户有权限以另一个用户的身份修改Review Request。
以如下的命令方式调用post-review：
post-review --username=SPECIAL_USER --password=PASSWORD --submit-as=ANOTHER_USER
当然也可以根据实际情况使用任何其他的参数和值，这将以用户SPECIAL_USER登录，但以用户ANOTHER_USER操作。
配置
为集成ReviewBoard服务器和版本库而进行的post-review配置有很多种方式。最理想的方式是配置版本库指向ReviewBoard服务器，这样用户就可以非常方便的使用post-review。不过还有其他的配置方式。
版本库配置
有些类型的版本库可以用特定的元数据和Review Board服务器关联，所有类型的版本库都支持per-directory dot files。
GIT属性
版本库信息可以设置在Git树的reviewboard:url属性中，用户可能需要在自己的Git树中设置，因此某些情况下使用点文件会比较好。
要设置Git的属性，使用命令：
git config reviewboard.url http://reviewboard.example.com
Subversion属性
版本库信息可以设置在目录的reviewboard:url属性中，通常设置在checkout的目录中，如/trunk或/trunk/myproject等，如果目录是用户的checkout目录，找到该属性会比较快。
要设置目录的属性，输入命令：
svn propset reviewboard:url http://reviewboard.example.com .
.reviewboardrc
.reviewboardrc文件是配置版本库的地方，该文件必须放在包含用户checkout的工作拷贝目录所在的路径中，它必须是一个有效的python文件，否则在使用post-review会出现错误。
版本库
通常情况下，版本库路径会自动确定，但在某些更复杂的配置环境下，你需要为post-review和Review Board指定要使用的是哪个版本库。
可以使用REPOSITORY环境变量设置指定版本库路径或者版本库ID，如：
REPOSITORY = 'https://svn.example.com/'
如果使用的Review Board版本是1.5.3或更高版本，也可以选择版本库名称，这和提交新的Review Request时指定的名称一样，如：
REPOSITORY = 'RBTools’
REVIEWBOARD_URL
使用REVIEWBOARD_URL环境变量可以指定要使用的Review Board服务器，值就是服务器的URL，如：
REVIEWBOARD_URL = "http://reviewboard.example.com"
定制用户配置
如果没有为post-review配置版本库，也没有使用定制的脚本，你可以在你的HOME目录下创建一个.reviewboardrc文件（在Linux上，通常是/home/username，在Windows上则是指目录$USERPROFILE\Local Settings\Application Data）。
最简单的情况，文件只包含有一个ReviewBoard服务器的URL：
REVIEWBOARD_URL = "http://reviewboard.example.com"
更复杂的情况，是根据版本库路径配置服务器，如：
TREES = {
'REVIEWBOARD_URL': 'http://reviewboard.example.com',
},
'[email protected]:/cvsroot/cvs': {
'REVIEWBOARD_URL': 'http://reviewboard.example.com',
},
}
不限制版本库路径的数量，版本库路径必须和ReviewBoard服务器上配置的版本库匹配。
post-review命令参数选项
基本选项
-d, --debug
在终端显示详细的debug输出信息；
-h, --help
显示post-review命令的帮助信息；
-o, --open
打开Web浏览器，显示post-review命令创建或更新的ReviewRequest。
--version
显示版本号。
服务器选项
--server=<URL>
指定所使用的Review Board服务器的URL。默认情况下，post-review会扫描合适的版本库。
--submit-as=<USERNAME>
指定用于更新Review Request的用户名，这和--username不同。此用户名不用于登录Review Board服务器，为正常使用，必须使用有特定权限的用户账号登录。一般用于在版本库的post-commit脚本中自动创建或更新Review Request。
--username=<USERNAME>
指定用于登录Review Board服务器的用户，如果未指定，post-review命令会提示输入用户名。
--password=<PASSWORD>
指定用来登录Review Board服务器的用户密码，如果没有指定，post-review命令会提示输入密码。
Review Request Options
-p, --publish
提交后马上正式发布Review Request，正常情况下新提交的Review Request以初稿存在，需要后续补充完善相关信息后正式提交。
-r <ID>, --review-request-id=<ID>
更新已有的Review Request，而不是新建一个。ID是已存在的Review Request的序号。
--revision-range=
指定用于创建diff文件的版本范围。
字段默认选项
--branch=<BRANCH>
设置Review Request的branch字段信息。
--bugs-closed=
指定Bug ID列表（以逗号隔开）。
--description=<DESCRIPTION>
设置Review Request的Description字段信息。
--description-file=<FILENAME>
以指定的文件内容来设置Review Request的Description字段信息。
--diff-filename=<FILENAME>
指定已有的diff文件，而不是创建新的diff文件，上传到Review Request。可使用特定的值-。
--summary=<SUMMARY>
设置Review Request的summary字段信息。
--target-groups=
提供一组在Reviewer列表中的群组名，以逗号隔开。
--target-people=
提供一组以逗号隔开的Reviewer列表的用户名。
--testing-done=
设置Review Request的testing done字段信息。
--testing-done-file=<FILENAME>
以指定文件内容设置设置Review Request的testing done字段信息。
ClearCase Options
--label=<LABEL>
指定ClearCase使用的特定标签。
Git Options
--guess-description
基于父分支和HEAD之间所有commit的信息，设置Review Request的Description信息。不能和--description参数一起使用。
--guess-summary
基于最新的commit消息设置Review Request的summary信息，不能和--summary参数一起使用。
Git and Mercurial Options
--parent=
指定diff基础的父分支，但在修改内容的分支基于另一个未提交的分支上时，必须使用此参数。
Perforce Options
--change-only
基于提供的变更号，更新Review Request信息，包括description，testing done等等，但不包括diff文件。
基于提供的变更号，上传新的diff，但不更新Review Request信息（如Description，testing done等等）。
--p4-client=
指定创建diff时所使用的Perforce客户端名称。
--p4-port=
指定创建diff文件时所使用的Perforce服务器IP地址。
--p4-passwd=
指定用于认证版本库的Perforce Ticket或文本密码。
Subversion Options
--repository-url=<URL>
指定创建diff时使用的Subversion版本库URL，必须和--revision-range参数同时使用。