手冊

與錯誤追蹤系統 / 問題追蹤器的整合

在軟體開發中,變更與特定的錯誤或問題 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

此屬性定義是否將錯誤 ID 附加 (true) 到提交訊息的末尾,或插入 (false) 到提交訊息的開頭。有效值為 true/false 如果未定義,則假定為 true,以便現有專案不會中斷。

使用正規表示式的問題編號

在使用正規表示式的方法中,TortoiseSVN 不會顯示單獨的輸入欄位,而是標記使用者輸入的提交訊息中被問題追蹤器識別的部分。這是在使用者撰寫提交訊息時完成的。這也表示錯誤 ID 可以位於提交訊息內的任何位置!這種方法更具彈性,也是 TortoiseSVN 專案本身使用的方法。

bugtraq:logregex

此屬性以Regex模式啟用錯誤追蹤系統。它包含單個正規表示式,或兩個以換行符分隔的正規表示式。

如果設定了兩個表示式,則第一個表示式用作預先篩選器,以尋找包含錯誤 ID 的表示式。然後,第二個表示式從第一個正規表示式的結果中提取裸錯誤 ID。如果您希望使用錯誤 ID 列表和自然語言表示式,這允許您這樣做。例如,您可能會修復多個錯誤,並包含類似於以下的字串:This change resolves issues #23, #24 and #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 上的簡介,以及 https://regular-expressions.dev.org.tw/ 上的線上文件和教學課程。

並非總是容易獲得正確的正規表示式,因此為了提供協助,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 屬性,因此您僅在使用簽出的工作副本時才會看到結果。遠端提取屬性是一個緩慢的操作,因此除非您從工作副本啟動儲存庫瀏覽器,否則您不會從儲存庫瀏覽器中看到此功能生效。如果您透過輸入儲存庫的 URL 來啟動儲存庫瀏覽器,您將不會看到此功能。

出於相同的原因,當使用儲存庫瀏覽器新增子資料夾時,專案屬性不會自動傳播。

此問題追蹤器整合不限於 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 首頁