手册

与错误跟踪系统/问题跟踪器的集成

在软件开发中,更改与特定的错误或问题 ID 相关联非常常见。错误跟踪系统(问题跟踪器)的用户希望将他们在 Subversion 中所做的更改与他们问题跟踪器中的特定 ID 相关联。因此,大多数问题跟踪器提供了一个预提交钩子脚本,该脚本解析日志消息以查找与提交关联的错误 ID。这有点容易出错,因为它依赖于用户正确编写日志消息,以便预提交钩子脚本可以正确地解析它。

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

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

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

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 不会显示单独的输入字段,而是会标记用户输入的日志消息中被问题跟踪器识别的那部分。这是在用户编写日志消息时完成的。这也意味着 bug ID 可以位于日志消息中的任何位置!这种方法更加灵活,也是 TortoiseSVN 项目本身使用的方法。

bugtraq:logregex

此属性在 Regex 模式下激活错误跟踪系统。它包含一个正则表达式,或者两个用换行符分隔的正则表达式。

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

如果您想在日志消息中捕获上面表达式中使用的 bug 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 的介绍,以及 https://regexper.cn/ 的在线文档和教程。

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

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

提示

即使您没有使用预提交钩子解析日志消息的问题跟踪器,您仍然可以使用它将日志消息中提到的问题转换为链接!

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

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

在文件夹上设置属性

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

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

对于项目属性 ,即 tsvn:bugtraq:webviewer:,您可以使用 递归 复选框将属性设置为层次结构中的所有子文件夹,而不会将其设置为所有文件。

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

从仓库浏览器中获取不到问题跟踪器信息

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

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

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

从问题跟踪器获取信息

上一节介绍了如何将问题信息添加到日志消息中。但是,如果您需要从问题跟踪器获取信息怎么办?提交对话框有一个 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 主页