漏洞報告準則

翻譯狀態：

• 本文（或部分內容）是 Bug reporting guidelines 的翻譯，最近一次同步的日期是 2023-03-30，如果英文版本有所更改，則您可以幫助同步翻譯更改的內容。
• 您可以在ArchWiki 的對應頁面找到本文翻譯的原始編輯記錄和貢獻者列表。

相關文章

• General troubleshooting
• Step-by-step debugging guide
• Debugging/Getting traces

在 Arch Linux 問題跟蹤系統 報告問題是 幫助社區 的一種方式。然而，質量不高的問題報告卻會起反作用，浪費開發者的時間。此文檔將像那些願意幫助社區的人給出有效報告問題和解決問題的指南。

參見 Simon Tatham 的 如何有效的報告問題。

開始之前

準備詳細規範的問題報告並不難，但是需要報告者付出精力。 報告前的工作才是最重要的。 不幸的是，很少有人花時間做好這個工作。

下面的步驟將指導您準備問題報告。

查找重複問題

當你遇到問題或要求一個新功能是，極有可能有人也遇到了同樣的問題，產生同樣的想法。一個問題報告可能已經存在。這時，不要創建重複問題，請跟蹤原有問題。

全面查找已有信息，包括：

• Arch Linux 論壇: 論壇通常是用戶尋求幫助和分享解決方案的第一處。就算當時問題可能沒有解決，各位用戶追加的信息和討論能幫助你找到正確的方向。
• Arch Linux Bugtracker （Arch Linux Bug 管理系統）: 問題可能已經由其他的用戶提交給了開發者。重複的問題沒有什麼幫助，會被直接關閉。在高級中選擇全部狀態,可以同時搜索已解決和未解決的問題；問題標題可能不帶要搜索的關鍵字，請在高級中選擇'搜索詳情' 和 '搜索評論' 。
• 在Google 或者您常用的搜尋引擎中搜索: 試着搜索程序名稱、版本和相關的錯誤消息（如果有的話）。
• 上游 論壇,郵件列表和 Bug 回報系統: 如果 Arch Linux 不是造成 Bug 的原因，這個 Bug 應該提交到上游（而不是 Arch Linux）。試着搜索最近關閉的 Bug 報告和其它正在進行中的報告，你所遇到的 Bug 可能已經在上游被修復了。
• 其它發行版的論壇: 自由軟件社區很宏大，有想法的不只有 Archer ! 考慮一下搜索其它發行版的論壇，例如 Gentoo Forums, FedoraForum.org, 和 Ubuntu Forums。

上游還是 Arch?

Arch Linux 是一個 GNU/Linux 發行版 . Arch 開發者們和 Trusted User 們負責從各處編譯,打包並分發軟件.上游意味着來源 – 就是 Arch Linux 所分發的軟件的來源.例如 FireFox 瀏覽器是由 Mozilla 開發的.

如果 Arch 不是造成 Bug 的主要原因,把 Bug 報告提交到 Arch 開發者並不能解決問題.

通過向上游提交 Bug 報告,你不只幫助到了 Arch Linux 用戶和開發者,同時也是在幫助自由軟件社區的其他用戶們.這樣其它發行版的用戶也能從中獲得解決方案.

如果你從上游獲得了相關的信息,也許可以把它們發送到 Arch Linux Bugtracker ,這樣 Arch 開發者和用戶們便能從中了解一些信息.

所以 Arch Linux 負責什麼?

• Arch Linux 項目: pacman, AUR, mkinitcpio, Arch Linux 網站. 不知道這個包是不是 Arch 的項目? 查找項目信息 (pacman -Qi package_name 或者通過網站) 並從中尋找上游網址 .

注意： Report issues for Arch Linux software projects in the project's respective issue tracker on gitlab.archlinux.org or GitHub instead of bugs.archlinux.org.

• 打包: 打包包含從上游獲取原始碼,用相關的選項編譯,確認它能在 Arch 上正確安裝與運行等環節. Arch 的 打包環節不包含增加新功能或是修復 Bug ,這些是上游開發者的工作.

如果某個 Bug/Feature 不是 Arch 的原因,請把它提交給上游.另參閱 有些不是 Bug 的原因.

Bug 或者 Feature?

bug

某些該工作的地方沒有按開發者的預期工作.

feature

something which software does or would do if somebody coded it.

有些不該提交 Bug 報告的原因

• 你想要一個還沒有的功能（這是功能請求）。
• 已經提交給上游的 Bug
• 上游已經修復但是 Arch 還沒更新軟件包。
• 某個軟件包過期了，這種情況請使用 Arch Linux 網站上的 標記這個包已過期 按鈕.
• 某個軟件包沒使用來自其它發行版或其它社區的補丁,補丁應該提交到上游.
• 某個軟件包中的 非核心功能 沒有啟用.這種情況應該提交功能請求.
• 某個軟件包沒有包含 freedesktop 相關文件,例如 .desktop 文件 或是 圖標.只有在上游提供了這些文件但軟件包中沒有使用的情況下才是個 Bug .如果該上游沒有提供這些文件,那麼應該向上游提交功能請求.

有些不是 Feature 的原因

• 這是個 Bug ......
• 某個軟件包過期了，這種情況請使用 Arch Linux 網站上的 標記這個包已過期 按鈕.
• 某個軟件包沒使用來自其它發行版或其它社區的補丁,補丁應該提交到上游.

收集有用的信息

這是一個關於你的 Bug 報告中應該包含的信息的列表:

• 軟件包的具體版本,類似於"最新的","今天的","[Extra]中的"這樣的描述毫無意義.
• 軟件包所使用的庫 (可以在 PKGBUILD 中的 depends 中找到 ),它們可能和問題相關.如果你不知道確切的信息,那就等別人來問......
• 如果遇到了硬件問題,記得提供內核版本和硬件生產廠家。
• 這個功能 是否有正常工作過 .如果有的話,什麼時間停止工作的.
• 如果有的話,提供其它 相關的日誌 這些信息可能會幫助找到問題所在:
  • Systemd 日誌.如果使用syslog-ng^包, /var/log/messages 包含內核和硬件相關問題的信息.
  • /var/log/Xorg.0.log , /var/log/Xorg.2.log 或其他 Xorg 日誌包含顯示相關的問題的信息.
  • 通過 verbose 或是 debug 模式在終端運行你的程序並收集其輸出 (如果有的話,請參閱你的程序提供的文檔) . 對於母語不是英語的用戶,你也許需要在終端中設置相應的環境變量 (例如export LC_ALL="C") 以使程序以英文輸出.這樣更多的人便可以讀懂它.例如在終端下以 --verbose 選項運行 foobar:

$ export LC_ALL="C"
$ foobar --verbose

這樣改變環境變量只對當前終端生效.

如果需要提供大量的文本,例如 dmesg 的輸出或是 Xorg 日誌,最好把它們保存到文件中並隨着 Bug 報告提供. 但是請保證提供的文件和 Bug 相關.

• 復現 Bug 的方法.這很重要,因為這樣可以幫助其他人測試 Bug 是否修復和尋找潛在的修複方案.

• 堆棧跟蹤 .包含程序調用過程的列表,這可以幫助定位問題的位置(特別是那些導致程序崩潰的問題).Debug - Getting Traces#Getting the trace 包含了使用gdb^包 (The GNU Debugger) 生成堆棧跟蹤的詳細信息.

新建一個 Bug 報告

在你收集到需要的信息並且確定是個 Bug 或者功能請求以後,你就可以提交 Bug 報告或者功能請求了.

創建賬戶

首先在 Arch 的 Bug 回報系統 上註冊一個賬戶,像 Wiki 和論壇一樣簡單.

各個項目

如果認為某個 Bug 或功能請求確實和 Arch 相關,應該將其放置在正確的項目裡.在創建報告時從左側選擇一個正確的項目:

• Arch Linux - testing, core, 或 extra 中的軟件包的問題. 也包含 Arch Linux 的文檔,網站(除了 AUR) 和安全問題.
• Arch User Repository (AUR) - AUR 網站代碼和伺服器相關.記住並不包含訪問AUR中軟件包的第三方程序.
• Community Packages - community 中的軟件包 . 這並不包含 unsupported (AUR) 中的軟件包.
• Release Engineering - 所有和發行相關的問題 (iso等......)

對於 AUR 上軟件包的問題,請使用 AUR 網站上的評論功能提交給 AUR 上該軟件包的維護者.

摘要

請編寫一個簡潔且有描述性的摘要,下面是一些建議:

• 不要寫成 "pkgname is broken after the last update" 這樣的,這不光沒描述性而且沒人知道 Arch 中的 "after last update" 是啥時候.
• 用方括號表示軟件包名稱,例如 "[pkgname] 3.0.5-1 breaks copy-paste feature" .合理的命名可以幫助開發者搜索和排列報告.
• 別太長,因為太長的內容會在列表中被截斷.

提示：Flyspray will try to parse URLs containing @ (e.g. links to mailing list archives) as email address links and fail miserably. To post such URLs, make sure to URL-encode @ as %40.

嚴重性

選擇一個嚴重性等級不會幫助更快的修復 Bug .這只是讓關鍵的問題易於搜索和被開發者標記.

Here is a general usage of severities: 常見的嚴重等級有這幾種:

• Critical(嚴重),導致系統崩潰或啟動失敗,可能影響到其他用戶的問題.或是對外服務的安全漏洞.
• High(高) - 程序的主要功能不工作,或是不那麼嚴重的安全問題等等.
• Medium(中等) - 程序的非主要功能不工作,不遵循 UNIX 規範等等.
• Low(低) - 程序的可選功能(插件或是編譯時選項)不工作.
• Very Low(很低) - 翻譯或是文檔錯誤,偶爾會是功能請求.

包括相關信息

這也許是 Bug 報告中最困難的一個階段,前面的收集有用的信息一節應該包含了需要的信息;如果不知道要提供什麼的話,記得"多多益善".

參見 Simon Tatham 的 如何有效的報告問題。

不過開發者可能會要求你提供更多信息,幸運的是在交談過幾次以後你應該會知道該提供哪些信息了.

短小的信息可以包含在你的報告裏,長的信息請使用附件功能隨附在報告裏.

追蹤 Bug

不要認為你提交完 Bug 報告就結束了! 開發者和其他用戶可能會詢問你細節或是提供一些方法.沒有持續的反饋會讓 Bug 報告有始無終,同時也會惹惱用戶和開發者們.

投票與監視

你可以為同樣影響到你的 Bug vote (投票).投票會讓開發者察覺有多少人受到了這個 Bug 的影響.但是如果你遇到了同樣的問題,提交相關的信息是比投票更快的解決方法.

Watching (監視/跟蹤) 一個 Bug 很重要,你會收到關於你跟蹤的 Bug 的進展的郵件.如果你提交了一個報告,請確保選中了 "Notify me whenever this task changes" (在 Task 改變時通知我) 選項.

回答追加的問題

其它人花時間閱讀報告並嘗試幫助你修復問題,你也應該盡所能向其他人提供你能做到的幫助.收不到回應不僅可能會讓你的 Bug 難以修復,還會讓幫助你的人失去信心.

如果其他人需要更多信息,請嘗試提供給他們.也請你嘗試一下可能的解決方案。.

開發者會關閉那些有新回復而提交 Bug 的人超過幾周或是一個月沒有回覆的 Bug 報告。

軟件新版本發佈時更新問題報告

有時某個 Bug 之在某些版本中出現，在新版本中已經修復，遇到這種情況的話記得在 Bug 報告中提出來然後提交一個關閉請求.

關閉已經解決的問題

有些時候用戶可能自己解決了自己遇到的 Bug ,遇到這種情況的話記得在 Bug 報告中提出來,附上解決方案的參考連結,然後提交一個關閉請求.

問題的狀態

一個 Bug 可能有下面這些狀態:

• Unconfirmed(未確認) - 這是默認狀態,表示還沒人確認或是復現這個 Bug.

• New(新的/已確認) - 表示這個 Bug 已經確認,但還沒關聯到相關軟件的負責人.通常是因為還沒確認哪個軟件引發的 Bug 的緣故.

• Assigned(已分配) - 這個 Bug 已經分配到與之關聯的開發者.不過這不意味着只有這個開發者會幫忙解決這個 Bug .這只是表示開發者會 關注這個Bug,例如檢查任何的修補,發表解決方案和在需要時關閉 Bug 報告.所以不要直接和這個被分配的開發者聯繫......

• Researching(研究中) - 有人正在尋求解決方案. 這通常表示這個 Bug 可能呢個需要更多經驗豐富的用戶幫忙解決.

• Waiting on Response(等待回復) 和 Requires testing(需要測試) - 有人提供了更多信息或是提供了一個可能的解決方法,但是需要反饋.Watching (監視/跟蹤) 一個 Bug 很重要,因為你可能會被開發者要求提供更詳細的信息.

• A task closure has been requested(已提交關閉請求) - 這不是最終狀態,但你也許會發現某些 Bug 報告是這樣的狀態.和它關聯的開發者會決定是否關閉它.

• Closed(已關閉) - 可能因為這不是個 Bug 有些不該提交 Bug 報告的原因 或者已經被解決.

像開發者和 TU 這樣的人負責管理和更新各個 Bug 的狀態.