手册

与缺陷跟踪系统 / 问题跟踪器的集成

在软件开发中,变更与特定的缺陷或问题 ID 相关联是非常常见的。缺陷跟踪系统(问题跟踪器)的用户希望将他们在 Subversion 中所做的更改与他们的问题跟踪器中的特定 ID 相关联。因此,大多数问题跟踪器都提供了一个 pre-commit hook 脚本,该脚本解析日志消息以查找与提交关联的缺陷 ID。但这在某种程度上容易出错,因为它依赖于用户正确编写日志消息,以便 pre-commit hook 脚本可以正确解析它。

TortoiseSVN 可以通过两种方式帮助用户

  1. 当用户输入日志消息时,可以自动添加包含与提交关联的问题编号的明确定义的行。这降低了用户以缺陷跟踪工具无法正确解析的方式输入问题编号的风险。

    或者 TortoiseSVN 可以高亮显示输入的日志消息中被问题跟踪器识别的部分。这样用户就知道日志消息可以被正确解析。

  2. 当用户浏览日志消息时,TortoiseSVN 会从日志消息中的每个缺陷 ID 创建一个链接,该链接会启动浏览器并跳转到提及的问题。

向日志消息添加问题编号

您可以在 TortoiseSVN 中集成您选择的缺陷跟踪工具。为此,您必须定义一些属性,这些属性以 bugtraq: 开头。它们必须在文件夹上设置:(名为“项目设置”的章节

图 4.70. Bugtraq 属性对话框

The Bugtraq Properties Dialog


当您编辑任何 bugtraq 属性时,会使用一个特殊的属性编辑器,以便更轻松地设置适当的值。

有两种方法可以将 TortoiseSVN 与问题跟踪器集成。一种是基于简单字符串,另一种是基于 正则表达式。两种方法使用的属性是

bugtraq:url

将此属性设置为您的缺陷跟踪工具的 URL。它必须经过正确的 URI 编码,并且必须包含 %BUGID%%BUGID% 将被替换为您输入的问题编号。这允许 TortoiseSVN 在日志对话框中显示一个链接,这样当您查看修订日志时,您可以直接跳转到您的缺陷跟踪工具。您不必提供此属性,但那样 TortoiseSVN 只会显示问题编号,而不会显示指向它的链接。

您也可以使用相对 URL 而不是绝对 URL。当您的问题跟踪器与您的源代码存储库位于同一域/服务器上时,这很有用。如果域名发生更改,您不必调整 bugtraq:url 属性。有两种方法可以指定相对 URL

如果它以字符串 ^/ 开头,则假定它相对于存储库根目录。例如,如果您的存储库位于 https://example.com/svn/trunk/ 上,则 ^/../?do=details&id=%BUGID% 将解析为 https://example.com/?do=details&id=%BUGID%

以字符串 / 开头的 URL 被假定为相对于服务器的主机名。例如,如果您的存储库位于 https://example.com 上的任何位置,则 /?do=details&id=%BUGID% 将解析为 https://example.com/?do=details&id=%BUGID%

bugtraq:warnifnoissue

如果您希望 TortoiseSVN 因为问题编号文本字段为空而警告您,请将其设置为 true。有效值为 true/false 如果未定义,则假定为 false

文本框中的问题编号

在简单方法中,TortoiseSVN 向用户显示一个单独的输入字段,可以在其中输入缺陷 ID。然后,将单独的一行附加/前置到用户输入的日志消息中。

bugtraq:message

此属性在 输入字段 模式下激活缺陷跟踪系统。如果设置了此属性,则当您提交更改时,TortoiseSVN 将提示您输入问题编号。它用于在日志消息的末尾添加一行。它必须包含 %BUGID%,在提交时该代码将被问题编号替换。这确保您的提交日志包含对问题编号的引用,该引用始终采用一致的格式,并且可以被您的缺陷跟踪工具解析,以将问题编号与特定的提交关联起来。例如,您可以使用 Issue : %BUGID%,但这取决于您的工具。

bugtraq:label

此文本由 TortoiseSVN 在提交对话框中显示,以标记您在其中输入问题编号的编辑框。如果未设置,则将显示 Bug-ID / Issue-Nr:。但请记住,窗口不会调整大小以适应此标签,因此请将标签的大小保持在 20-25 个字符以下。

bugtraq:number

如果设置为 true,则只允许在问题编号文本字段中使用数字。逗号是一个例外,因此您可以用逗号分隔多个数字。有效值为 true/false 如果未定义,则假定为 true

bugtraq:append

此属性定义了 bug-ID 是附加 (true) 到日志消息的末尾,还是插入 (false) 到日志消息的开头。有效值为 true/false 如果未定义,则假定为 true,以便现有项目不会中断。

使用正则表达式的问题编号

在使用 正则表达式 的方法中,TortoiseSVN 不会显示单独的输入字段,而是标记用户输入的日志消息中被问题跟踪器识别的部分。这是在用户编写日志消息时完成的。这也意味着缺陷 ID 可以位于日志消息中的任何位置!这种方法更加灵活,也是 TortoiseSVN 项目本身使用的方法。

bugtraq:logregex

此属性在 Regex 模式下激活缺陷跟踪系统。它包含单个正则表达式,或由换行符分隔的两个正则表达式。

如果设置了两个表达式,则第一个表达式用作预过滤器,以查找包含缺陷 ID 的表达式。然后,第二个表达式从第一个正则表达式的结果中提取裸缺陷 ID。如果您愿意,这允许您使用缺陷 ID 列表和自然语言表达式。例如,您可能修复了几个缺陷,并包含类似以下的字符串:此更改解决了问题 #23、#24 和 #25

如果您想捕获日志消息中上述表达式中使用的缺陷 ID,您可以使用以下正则表达式字符串,这些字符串是 TortoiseSVN 项目使用的字符串:[Ii]ssues?:?(\s*(,|and)?\s*#\d+)+(\d+)

第一个表达式从周围的日志消息中挑选出 issues #23, #24 and #25。第二个正则表达式从第一个正则表达式的输出中提取纯十进制数字,因此它将返回 232425 以用作缺陷 ID。

稍微分解一下第一个正则表达式,它必须以单词 issue 开头,可能是大写的。这后面可选地跟一个 s(多个问题)和可选的冒号。接下来是一个或多个组,每个组都有零个或多个前导空格,一个可选的逗号或 and 和更多可选空格。最后,有一个强制性的 # 和一个强制性的十进制数字。

如果只设置了一个表达式,则必须在正则表达式字符串的组中匹配裸缺陷 ID。示例:[Ii]ssue(?:s)? #?(\d+) 某些问题跟踪器(例如 trac)需要此方法,但构造正则表达式更困难。我们建议您仅在问题跟踪器文档告诉您这样做时才使用此方法。

如果您不熟悉正则表达式,请查看 https://en.wikipedia.org/wiki/Regular_expression 上的介绍,以及 http://regexper.cn/ 上的在线文档和教程。

要获得正确的正则表达式并不总是那么容易,因此为了提供帮助,bugtraq 属性对话框中内置了一个测试对话框。单击编辑框右侧的按钮将其调出。在这里,您可以输入一些测试文本,并更改每个正则表达式以查看结果。如果正则表达式无效,则编辑框背景会变为红色。

如果同时设置了 bugtraq:messagebugtraq:logregex 属性,则 logregex 优先。

提示

即使您没有使用 pre-commit hook 解析您的日志消息的问题跟踪器,您仍然可以使用此功能将日志消息中提及的问题转换为链接!

即使您不需要链接,问题编号也会在日志对话框中显示为单独的一列,从而更容易找到与特定问题相关的更改。

某些 tsvn: 属性需要 true/false 值。TortoiseSVN 也将 yes 理解为 true 的同义词,将 no 理解为 false 的同义词。

在文件夹上设置属性

这些属性必须在文件夹上设置才能使系统正常工作。当您提交文件或文件夹时,将从该文件夹读取属性。如果在那里找不到属性,TortoiseSVN 将在文件夹树中向上搜索以查找它们,直到找到未版本化的文件夹或树根(例如 C:\)。如果您可以确定每个用户仅从例如 trunk/ 而不是某些子文件夹检出,那么如果您在 trunk/ 上设置属性就足够了。如果您不能确定,则应在每个子文件夹上递归设置属性。项目层次结构中较深层的属性设置将覆盖更高层(更接近 trunk/)的设置。

从 1.8 版开始,TortoiseSVN 和 Subversion 使用所谓的 继承属性,这意味着在文件夹上设置的属性也会自动隐式地设置在所有子文件夹上。因此,不再需要在所有文件夹上设置属性,而只需在根文件夹上设置属性即可。

对于项目属性仅限,即 tsvn:bugtraq:webviewer:,您可以使用 递归 复选框将属性设置为层次结构中的所有子文件夹,而无需同时在所有文件上设置它。

当您使用 TortoiseSVN 向工作副本添加新的子文件夹时,父文件夹中存在的任何项目属性都将自动添加到新的子文件夹中。

存储库浏览器中没有问题跟踪器信息

由于问题跟踪器集成依赖于访问 Subversion 属性,因此您只有在使用检出的工作副本时才能看到结果。远程获取属性是一个缓慢的操作,因此除非您从工作副本启动存储库浏览器,否则您不会在 repo 浏览器中看到此功能。如果您通过输入存储库的 URL 启动了存储库浏览器,您将看不到此功能。

出于同样的原因,当使用 repo 浏览器添加子文件夹时,项目属性不会自动传播。

此问题跟踪器集成不限于 TortoiseSVN;它可以与任何 Subversion 客户端一起使用。有关更多信息,请阅读 TortoiseSVN 源代码存储库中的完整 Issue Tracker Integration Specification 。(名为“许可证”的章节 解释了如何访问存储库。)

从问题跟踪器获取信息

上一节介绍了如何将问题信息添加到日志消息中。但是,如果您需要从问题跟踪器获取信息怎么办?提交对话框具有 COM 接口,该接口允许集成可以与您的跟踪器对话的外部程序。通常,您可能需要查询跟踪器以获取分配给您的未解决问题列表,以便您可以选择在此提交中解决的问题。

当然,任何此类接口都高度特定于您的问题跟踪器系统,因此我们无法提供此部分,并且描述如何创建此类程序超出了本手册的范围。接口定义和 C# 和 C++/ATL 中的示例插件可以从 TortoiseSVN 存储库 中的 contrib 文件夹中获得。(名为“许可证”的章节 解释了如何访问存储库。)第 7 章,IBugtraqProvider 接口 中也给出了 API 的摘要。另一个(可工作的)C# 示例插件是 Gurtle ,它实现了与 Google Code 问题跟踪器交互所需的 COM 接口。Google Code 本身已于 2016 年关闭,但该插件仍然可用作示例实现。

为了说明目的,假设您的系统管理员为您提供了一个问题跟踪器插件,您已安装该插件,并且您已在 TortoiseSVN 的设置对话框中设置了一些工作副本以使用该插件。当您从已分配插件的工作副本打开提交对话框时,您将在对话框顶部看到一个新按钮。

图 4.71. 问题跟踪器查询对话框示例

Example issue tracker query dialog


在此示例中,您可以选择一个或多个未解决的问题。然后,插件可以生成特殊格式的文本,并将其添加到您的日志消息中。

TortoiseSVN 主页