Documentation/translations/zh_TW/admin-guide/reporting-issues.rst

.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
..
   If you want to distribute this text under CC-BY-4.0 only, please use 'The
   Linux kernel developers' for author attribution and link this as source:
   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst
..
   Note: Only the content of this RST file as found in the Linux kernel sources
   is available under CC-BY-4.0, as versions of this text that were processed
   (for example by the kernel's build system) might contain content taken from
   files which use a more restrictive license.

.. include:: ../disclaimer-zh_TW.rst

:Original: Documentation/admin-guide/reporting-issues.rst

:譯者:

 吳想成 Wu XiangCheng <bobwxc@email.cn>
 胡皓文 Hu Haowen <src.res@email.cn>


報告問題
+++++++++


簡明指南（亦即 太長不看）
==========================

您面臨的是否爲同系列穩定版或長期支持內核的普通內核的回歸？是否仍然受支持？
請搜索 `LKML內核郵件列表 <https://lore.kernel.org/lkml/>`_ 和
`Linux穩定版郵件列表 <https://lore.kernel.org/stable/>`_ 存檔中匹配的報告並
加入討論。如果找不到匹配的報告，請安裝該系列的最新版本。如果它仍然出現問題，
報告給穩定版郵件列表（stable@vger.kernel.org）。

在所有其他情況下，請儘可能猜測是哪個內核部分導致了問題。查看MAINTAINERS文件，
了解開發人員希望如何得知問題，大多數情況下，報告問題都是通過電子郵件和抄送
相關郵件列表進行的。檢查報告目的地的存檔中是否已有匹配的報告；也請搜索
`LKML <https://lore.kernel.org/lkml/>`_ 和網絡。如果找不到可加入的討論，請
安裝 `最新的主線內核 <https://kernel.org/>`_ 。如果仍存在問題，請發送報告。

問題已經解決了，但是您希望看到它在一個仍然支持的穩定版或長期支持系列中得到
解決？請安裝其最新版本。如果它出現了問題，那麼在主線中搜索修復它的更改，並
檢查是否正在回傳（backporting）或者已放棄；如果兩者都沒有，那麼可詢問處理
更改的人員。

**通用提醒** ：當安裝和測試上述內核時，請確保它是普通的（即：沒有補丁，也沒
有使用附加模塊）。還要確保它是在一個正常的環境中構建和運行，並且在問題發生
之前沒有被汙染（tainted）。

在編寫報告時，要涵蓋與問題相關的所有信息，如使用的內核和發行版。在碰見回歸時，
嘗試給出引入它的更改的提交ID，二分可以找到它。如果您同時面臨Linux內核的多個
問題，請分別報告每個問題。

一旦報告發出，請回答任何出現的問題，並儘可能地提供幫助。這包括通過不時重新
測試新版本並發送狀態更新來推動進展。


如何向內核維護人員報告問題的逐步指南
=====================================

上面的簡明指南概述了如何向Linux內核開發人員報告問題。對於已經熟悉向自由和開
源軟體（FLOSS）項目報告問題的人來說，這可能是他們所需要的全部內容。對於其他
人，本部分更爲詳細，並一步一步地描述。爲了便於閱讀，它仍然儘量簡潔，並省略
了許多細節；這些在逐步指南後的參考章節中進行了描述，該章節更詳細地解釋了每
個步驟。

注意：本節涉及的方面比簡明指南多，順序也稍有不同。這符合你的利益，以確保您
儘早意識到看起來像Linux內核毛病的問題可能實際上是由其他原因引起的。這些步驟
可以確保你最終不會覺得在這一過程中投入的時間是浪費：

 * 您是否面臨硬體或軟體供應商提供的Linux內核的問題？那麼基本上您最好停止閱讀
   本文檔，轉而向您的供應商報告問題，除非您願意自己安裝最新的Linux版本。尋找
   和解決問題往往需要後者。

 * 使用您喜愛的網絡搜尋引擎對現有報告進行粗略搜索；此外，請檢查
   `Linux內核郵件列表（LKML） <https://lore.kernel.org/lkml/>`_ 的存檔。如果
   找到匹配的報告，請加入討論而不是發送新報告。

 * 看看你正在處理的問題是否爲回歸問題、安全問題或非常嚴重的問題：這些都是需
   要在接下來的一些步驟中特別處理的「高優先級問題」。

 * 確保不是內核環境導致了您面臨的問題。

 * 創建一個新的備份，並將系統修復和恢復工具放在手邊。

 * 確保您的系統不會通過動態構建額外的內核模塊來增強其內核，像DKMS這樣的解決
   方案可能在您不知情的情況下就在本地進行了這樣的工作。

 * 當問題發生時，檢查您的內核是否被「汙染」，因爲使內核設置這個標誌的事件可能
   會導致您面臨的問題。

 * 粗略地寫下如何重現這個問題。如果您同時處理多個問題，請爲每個問題單獨寫注
   釋，並確保它們在新啓動的系統上獨立出現。這是必要的，因爲每個問題都需要分
   別報告給內核開發人員，除非它們嚴重糾纏在一起。

 * 如果您正面臨穩定版或長期支持版本線的回歸（例如從5.10.4更新到5.10.5時出現
   故障），請查看後文「報告穩定版和長期支持內核線的回歸」小節。

 * 定位可能引起問題的驅動程序或內核子系統。找出其開發人員期望的報告的方式和
   位置。注意：大多數情況下不會是 bugzilla.kernel.org，因爲問題通常需要通
   過郵件發送給維護人員和公共郵件列表。

 * 在缺陷追蹤器或問題相關郵件列表的存檔中徹底搜索可能與您的問題匹配的報告。
   如果你發現了一些相關討論，請加入討論而不是發送新的報告。

在完成這些準備之後，你將進入主要部分：

 * 除非您已經在運行最新的「主線」Linux內核，否則最好在報告流程前安裝它。在某些
   情況下，使用最新的「穩定版」Linux進行測試和報告也是可以接受的替代方案；在
   合併窗口期間，這實際上可能是最好的方法，但在開發階段最好還是暫停幾天。無論
   你選擇什麼版本，最好使用「普通」構建。忽略這些建議會大大增加您的報告被拒絕
   或忽略的風險。

 * 確保您剛剛安裝的內核在運行時不會「汙染」自己。

 * 在您剛剛安裝的內核中復現這個問題。如果它沒有出現，請查看下方只發生在
   穩定版和長期支持內核的問題的說明。

 * 優化你的筆記：試著找到並寫出最直接的復現問題的方法。確保最終結果包含所有
   重要的細節，同時讓第一次聽說的人容易閱讀和理解。如果您在此過程中學到了一
   些東西，請考慮再次搜索關於該問題的現有報告。

 * 如果失敗涉及「panic」、「Oops」、「warning」或「BUG」，請考慮解碼內核日誌以查找觸
   發錯誤的代碼行。

 * 如果您的問題是回歸問題，請儘可能縮小引入問題時的範圍。

 * 通過詳細描述問題來開始編寫報告。記得包括以下條目：您爲復現而安裝的最新內
   核版本、使用的Linux發行版以及關於如何復現該問題的說明。如果可能，將內核
   構建配置（.config）和 ``dmesg`` 的輸出放在網上的某個地方，並連結到它。包
   含或上傳所有其他可能相關的信息，如Oops的輸出/截圖或來自 ``lspci`` 的輸出
   。一旦你寫完了這個主要部分，請在上方插入一個正常長度的段落快速概述問題和
   影響。再在此之上添加一個簡單描述問題的句子，以得到人們的閱讀。現在給出一
   個更短的描述性標題或主題。然後就可以像MAINTAINERS文件告訴你的那樣發送或
   提交報告了，除非你在處理一個「高優先級問題」：它們需要按照下面「高優先級問
   題的特殊處理」所述特別關照。

 * 等待別人的反應，繼續推進事情，直到你能夠接受這樣或那樣的結果。因此，請公
   開和及時地回應任何詢問。測試提出的修復。積極地測試：至少重新測試每個新主
   線版本的首個候選版本（RC），並報告你的結果。如果出現拖延，就友好地提醒一
   下。如果你沒有得到任何幫助或者未能滿意，請試著自己幫助自己。


報告穩定版和長期支持內核線的回歸
----------------------------------

如果您發現了穩定版或長期支持內核版本線中的回歸問題並按上述流程跳到這裡，那麼
請閱讀本小節。即例如您在從5.10.4更新到5.10.5時出現了問題（從5.9.15到5.10.5則
不是）。開發人員希望儘快修復此類回歸，因此有一個簡化流程來報告它們：

 * 檢查內核開發人員是否仍然維護你關心的Linux內核版本線：去 `kernel.org 的首頁
   <https://kernel.org/>`_ ，確保此特定版本線的最新版沒有「[EOL]」標記。

 * 檢查 `Linux穩定版郵件列表 <https://lore.kernel.org/stable/>`_ 中的現有報告。

 * 從特定的版本線安裝最新版本作爲純淨內核。確保這個內核沒有被汙染，並且仍然
   存在問題，因爲問題可能已經在那裡被修復了。如果您第一次發現供應商內核的問題，
   請檢查已知最新版本的普通構建是否可以正常運行。

 * 向Linux穩定版郵件列表發送一個簡短的問題報告(stable@vger.kernel.org)。大致
   描述問題，並解釋如何復現。講清楚首個出現問題的版本和最後一個工作正常的版本。
   然後等待進一步的指示。

下面的參考章節部分詳細解釋了這些步驟中的每一步。


報告只發生在較舊內核版本線的問題
----------------------------------

若您嘗試了上述的最新主線內核，但未能在那裡復現問題，那麼本小節適用於您；以下
流程有助於使問題在仍然支持的穩定版或長期支持版本線，或者定期基於最新穩定版或
長期支持內核的供應商內核中得到修復。如果是這種情況，請執行以下步驟：

 * 請做好準備，接下來的幾個步驟可能無法在舊版本中解決問題：修復可能太大或太
   冒險，無法移植到那裡。

 * 執行前節「報告穩定版和長期支持內核線的回歸」中的前三個步驟。

 * 在Linux內核版本控制系統中搜索修復主線問題的更改，因爲它的提交消息可能會
   告訴你修復是否已經計劃好了支持。如果你沒有找到，搜索適當的郵件列表，尋找
   討論此類問題或同行評議可能修復的帖子；然後檢查討論是否認爲修復不適合支持。
   如果支持根本不被考慮，加入最新的討論，詢問是否有可能。

 * 前面的步驟之一應該會給出一個解決方案。如果仍未能成功，請向可能引起問題的
   子系統的維護人員詢問建議；抄送特定子系統的郵件列表以及穩定版郵件列表

下面的參考章節部分詳細解釋了這些步驟中的每一步。


參考章節：向內核維護者報告問題
===============================

上面的詳細指南簡要地列出了所有主要步驟，這對大多數人來說應該足夠了。但有時，
即使是有經驗的用戶也可能想知道如何實際執行這些步驟之一。這就是本節的目的，
因爲它將提供關於上述每個步驟的更多細節。請將此作爲參考文檔：可以從頭到尾
閱讀它。但它主要是爲了瀏覽和查找如何實際執行這些步驟的詳細信息。

在深入挖掘細節之前，我想先給你一些一般性建議：

 * Linux內核開發人員很清楚這個過程很複雜，比其他的FLOSS項目要求更多。我們很
   希望讓它更簡單。但這需要在不同的地方以及一些基礎設施上付諸努力，這些基礎
   設施需要持續的維護；尚未有人站出來做這些工作，所以目前情況就是這樣。

 * 與某些供應商簽訂的保證或支持合同並不能使您有權要求上游Linux內核社區的開
   發人員進行修復：這樣的合同完全在Linux內核、其開發社區和本文檔的範圍之外。
   這就是爲什麼在這種情況下，你不能要求任何契約保證，即使開發人員處理的問
   題對供應商有效。如果您想主張您的權利，使用供應商的支持渠道代替。當這樣做
   的時候，你可能想提出你希望看到這個問題在上游Linux內核中修復；可以這是確
   保最終修復將被納入所有Linux發行版的唯一方法來鼓勵他們。

 * 如果您從未向FLOSS項目報告過任何問題，那麼您應該考慮閱讀 `如何有效地報告
   缺陷 <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_ ， `如何
   以明智的方式提問 <http://www.catb.org/esr/faqs/smart-questions.html>`_ ，
   和 `如何提出好問題 <https://jvns.ca/blog/good-questions/>`_ 。

解決這些問題之後，可以在下面找到如何正確地向Linux內核報告問題的詳細信息。


確保您使用的是上游Linux內核
----------------------------

   *您是否面臨硬體或軟體供應商提供的Linux內核的問題？那麼基本上您最好停止閱
   讀本文檔，轉而向您的供應商報告問題，除非您願意自己安裝最新的Linux版本。
   尋找和解決問題往往需要後者。*

與大多數程式設計師一樣，Linux內核開發人員不喜歡花時間處理他們維護的原始碼中根本
不會發生的問題的報告。這只會浪費每個人的時間，尤其是你的時間。不幸的是，當
涉及到內核時，這樣的情況很容易發生，並且常常導致雙方氣餒。這是因爲幾乎所有預
裝在設備（台式機、筆記本電腦、智慧型手機、路由器等）上的Linux內核，以及大多數
由Linux發行商提供的內核，都與由kernel.org發行的官方Linux內核相距甚遠：從Linux
開發的角度來看，這些供應商提供的內核通常是古老的或者經過了大量修改，通常兩點
兼具。

大多數供應商內核都不適合用來向Linux內核開發人員報告問題：您在其中遇到的問題
可能已經由Linux內核開發人員在數月或數年前修復；此外，供應商的修改和增強可能
會導致您面臨的問題，即使它們看起來很小或者完全不相關。這就是爲什麼您應該向
供應商報告這些內核的問題。它的開發者應該查看報告，如果它是一個上游問題，直接
於上游修復或將報告轉發到那裡。在實踐中，這有時行不通。因此，您可能需要考慮
通過自己安裝最新的Linux內核內核來繞過供應商。如果如果您選擇此方法，那麼本指
南後面的步驟將解釋如何在排除了其他可能導致您的問題的原因後執行此操作。

注意前段使用的詞語是「大多數」，因爲有時候開發人員實際上願意處理供應商內核出現
的問題報告。他們是否這麼做很大程度上取決於開發人員和相關問題。如果發行版只
根據最近的Linux版本對內核進行了較小修改，那麼機會就比較大；例如對於Debian
GNU/Linux Sid或Fedora Rawhide所提供的主線內核。一些開發人員還將接受基於最新
穩定內核的發行版內核問題報告，只要它改動不大；例如Arch Linux、常規Fedora版本
和openSUSE Turboweed。但是請記住，您最好使用主線Linux，並避免在此流程中使用
穩定版內核，如「安裝一個新的內核進行測試」一節中所詳述。

當然，您可以忽略所有這些建議，並向上游Linux開發人員報告舊的或經過大量修改的
供應商內核的問題。但是注意，這樣的報告經常被拒絕或忽視，所以自行小心考慮一下。
不過這還是比根本不報告問題要好：有時候這樣的報告會直接或間接地幫助解決之後的
問題。


搜索現有報告（第一部分）
-------------------------

    *使用您喜愛的網絡搜尋引擎對現有報告進行粗略搜索；此外，請檢查Linux內核
    郵件列表（LKML）的存檔。如果找到匹配的報告，請加入討論而不是發送新報告。*

報告一個別人已經提出的問題，對每個人來說都是浪費時間，尤其是作爲報告人的你。
所以徹底檢查是否有人已經報告了這個問題，這對你自己是有利的。在流程中的這一步，
可以只執行一個粗略的搜索：一旦您知道您的問題需要報告到哪裡，稍後的步驟將告訴
您如何詳細搜索。儘管如此，不要倉促完成這一步，它可以節省您的時間和減少麻煩。

只需先用你最喜歡的搜尋引擎在網際網路上搜索。然後再搜索Linux內核郵件列表（LKML）
存檔。

如果搜索結果實在太多，可以考慮讓你的搜尋引擎將搜索時間範圍限制在過去的一個
月或一年。而且無論你在哪裡搜索，一定要用恰當的搜索關鍵詞；也要變化幾次關鍵
詞。同時，試著從別人的角度看問題：這將幫助你想出其他的關鍵詞。另外，一定不
要同時使用過多的關鍵詞。記住搜索時要同時嘗試包含和不包含內核驅動程序的名稱
或受影響的硬體組件的名稱等信息。但其確切的品牌名稱（比如說「華碩紅魔 Radeon
RX 5700 XT Gaming OC」）往往幫助不大，因爲它太具體了。相反，嘗試搜索術語，如
型號（Radeon 5700 或 Radeon 5000）和核心代號（「Navi」或「Navi10」），以及包含
和不包含其製造商（「AMD」）。

如果你發現了關於你的問題的現有報告，請加入討論，因爲你可能會提供有價值的額
外信息。這一點很重要，即使是在修復程序已經準備好或處於最後階段，因爲開發人
員可能會尋找能夠提供額外信息或測試建議修復程序的人。跳到「發布報告後的責任」
一節，了解有關如何正確參與的細節。

注意，搜索 `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 網站可能
也是一個好主意，因爲這可能會提供有價值的見解或找到匹配的報告。如果您發現後者，
請記住：大多數子系統都希望在不同的位置報告，如下面「你需要將問題報告到何處」
一節中所述。因此本應處理這個問題的開發人員甚至可能不知道bugzilla的工單。所以
請檢查工單中的問題是否已經按照本文檔所述得到報告，如果沒有，請考慮這樣做。

高優先級的問題？
-----------------

    *看看你正在處理的問題是否是回歸問題、安全問題或非常嚴重的問題：這些都是
    需要在接下來的一些步驟中特別處理的「高優先級問題」。*

Linus Torvalds和主要的Linux內核開發人員希望看到一些問題儘快得到解決，因此在
報告過程中有一些「高優先級問題」的處理略有不同。有三種情況符合條件:回歸、安全
問題和非常嚴重的問題。

如果在舊版本的Linux內核中工作的東西不能在新版本的Linux內核中工作，或者某種
程度上在新版本的Linux內核中工作得更差，那麼你就需要處理「回歸」。因此，當一個
在Linux 5.7中表現良好的WiFi驅動程序在5.8中表現不佳或根本不能工作時，這是一
種回歸。如果應用程式在新的內核中出現不穩定的現象，這也是一種回歸，這可能是
由於內核和用戶空間之間的接口（如procfs和sysfs）發生不兼容的更改造成的。顯著
的性能降低或功耗增加也可以稱爲回歸。但是請記住:新內核需要使用與舊內核相似的
配置來構建（參見下面如何實現這一點）。這是因爲內核開發人員在實現新特性時有
時無法避免不兼容性；但是爲了避免回歸，這些特性必須在構建配置期間顯式地啓用。

什麼是安全問題留給您自己判斷。在繼續之前，請考慮閱讀
「Documentation/translations/zh_TW/admin-guide/security-bugs.rst」，
因爲它提供了如何最恰當地處理安全問題的額外細節。

當發生了完全無法接受的糟糕事情時，此問題就是一個「非常嚴重的問題」。例如，
Linux內核破壞了它處理的數據或損壞了它運行的硬體。當內核突然顯示錯誤消息
（「kernel panic」）並停止工作，或者根本沒有任何停止信息時，您也在處理一個嚴重
的問題。注意：不要混淆「panic」（內核停止自身的致命錯誤）和「Oops」（可恢復錯誤），
因爲顯示後者之後內核仍然在運行。


確保環境健康
--------------

    *確保不是內核所處環境導致了你所面臨的問題。*

看起來很像內核問題的問題有時是由構建或運行時環境引起的。很難完全排除這種問
題，但你應該儘量減少這種問題：

 * 構建內核時，請使用經過驗證的工具，因爲編譯器或二進位文件中的錯誤可能會導
   致內核出現錯誤行爲。

 * 確保您的計算機組件在其設計規範內運行；這對處理器、內存和主板尤爲重要。因
   此，當面臨潛在的內核問題時，停止低電壓或超頻。

 * 儘量確保不是硬體故障導致了你的問題。例如，內存損壞會導致大量的問題，這些
   問題會表現爲看起來像內核問題。

 * 如果你正在處理一個文件系統問題，你可能需要用 ``fsck`` 檢查一下文件系統，
   因爲它可能會以某種方式被損壞，從而導致無法預期的內核行爲。

 * 在處理回歸問題時，要確保沒有在更新內核的同時發生了其他變化。例如，這個問
   題可能是由同時更新的其他軟體引起的。也有可能是在你第一次重啓進入新內核時，
   某個硬體巧合地壞了。更新系統 BIOS 或改變 BIOS 設置中的某些內容也會導致
   一些看起來很像內核回歸的問題。


爲緊急情況做好準備
-------------------

    *創建一個全新的備份，並將系統修復和還原工具放在手邊*

我得提醒您，您正在和計算機打交道，計算機有時會出現意想不到的事情，尤其是當
您折騰其作業系統的內核等關鍵部件時。而這就是你在這個過程中要做的事情。因此，
一定要創建一個全新的備份；還要確保你手頭有修復或重裝作業系統的所有工具，
以及恢復備份所需的一切。


確保你的內核不會被增強
------------------------

    *確保您的系統不會通過動態構建額外的內核模塊來增強其內核，像DKMS這樣的解
    決方案可能在您不知情的情況下就在本地進行了這樣的工作。*

如果內核以任何方式得到增強，那麼問題報告被忽略或拒絕的風險就會急劇增加。這就
是爲什麼您應該刪除或禁用像akmods和DKMS這樣的機制：這些機制會自動構建額外內核
模塊，例如當您安裝新的Linux內核或第一次引導它時。也要記得同時刪除他們可能安裝
的任何模塊。然後重新啓動再繼續。

注意，你可能不知道你的系統正在使用這些解決方案之一：當你安裝 Nvidia 專有圖
形驅動程序、VirtualBox 或其他需要 Linux 內核以外的模塊支持的軟體時，它們通
常會靜默設置。這就是爲什麼你可能需要卸載這些軟體的軟體包，以擺脫任何第三方
內核模塊。


檢測「汙染」標誌
----------------

    *當問題發生時，檢查您的內核是否被「汙染」，因爲使內核設置這個標誌的事件可
    能會導致您面臨的問題。*

當某些可能會導致看起來完全不相關的後續錯誤的事情發生時，內核會用「汙染
（taint）」標誌標記自己。如果您的內核受到汙染，那麼您面臨的可能是這樣的錯誤。
因此在投入更多時間到這個過程中之前，儘早排除此情況可能對你有好處。這是這個
步驟出現在這裡的唯一原因，因爲這個過程稍後會告訴您安裝最新的主線內核；然後
您將需要再次檢查汙染標誌，因爲當它出問題的時候內核報告會關注它。

在正在運行的系統上檢查內核是否汙染非常容易：如果 ``cat /proc/sys/kernel/tainted``
返回「0」，那麼內核沒有被汙染，一切正常。在某些情況下無法檢查該文件；這就是
爲什麼當內核報告內部問題（「kernel bug」）、可恢復錯誤（「kernel Oops」）或停止
操作前不可恢復的錯誤（「kernel panic」）時，它也會提到汙染狀態。當其中一個錯
誤發生時，查看列印的錯誤消息的頂部，搜索以「CPU:」開頭的行。如果發現問題時內
核未被汙染，那麼它應該以「Not infected」結束；如果你看到「Tainted:」且後跟一些
空格和字母，那就被汙染了。

如果你的內核被汙染了，請閱讀「Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst」
以找出原因。設法消除汙染因素。通常是由以下三種因素之一引起的：

 1. 發生了一個可恢復的錯誤（「kernel Oops」），內核汙染了自己，因爲內核知道在
    此之後它可能會出現奇怪的行爲錯亂。在這種情況下，檢查您的內核或系統日誌，
    並尋找以下列文字開頭的部分::

       Oops: 0000 [#1] SMP

    如方括號中的「#1」所示，這是自啓動以來的第一次Oops。每個Oops和此後發生的
    任何其他問題都可能是首個Oops的後續問題，即使這兩個問題看起來完全不相關。
    通過消除首個Oops的原因並在之後復現該問題，可以排除這種情況。有時僅僅
    重新啓動就足夠了，有時更改配置後重新啓動可以消除Oops。但是在這個流程中
    不要花費太多時間在這一點上，因爲引起Oops的原因可能已經在您稍後將按流程
    安裝的新Linux內核版本中修復了。

 2. 您的系統使用的軟體安裝了自己的內核模塊，例如Nvidia的專有圖形驅動程序或
    VirtualBox。當內核從外部源（即使它們是開源的）加載此類模塊時，它會汙染
    自己：它們有時會在不相關的內核區域導致錯誤，從而可能導致您面臨的問題。
    因此，當您想要向Linux內核開發人員報告問題時，您必須阻止這些模塊加載。
    大多數情況下最簡單的方法是：臨時卸載這些軟體，包括它們可能已經安裝的任
    何模塊。之後重新啓動。

 3. 當內核加載駐留在Linux內核原始碼staging樹中的模塊時，它也會汙染自身。這
    是一個特殊的區域，代碼（主要是驅動程序）還沒有達到正常Linux內核的質量
    標準。當您報告此種模塊的問題時，內核受到汙染顯然是沒有問題的；只需確保
    問題模塊是造成汙染的唯一原因。如果問題發生在一個不相關的區域，重新啓動
    並通過指定 ``foo.blacklist=1`` 作爲內核參數臨時阻止該模塊被加載（用有
    問題的模塊名替換「foo」）。


記錄如何重現問題
------------------

    *粗略地寫下如何重現這個問題。如果您同時處理多個問題，請爲每個問題單獨寫
    注釋，並確保它們在新啓動的系統上獨立出現。這是必要的，因爲每個問題都需
    要分別報告給內核開發人員，除非它們嚴重糾纏在一起。*

如果你同時處理多個問題，必須分別報告每個問題，因爲它們可能由不同的開發人員
處理。在一份報告中描述多種問題，也會讓其他人難以將其分開。因此只有在問題嚴
重糾纏的情況下，才能將問題合併在一份報告中。

此外，在報告過程中，你必須測試該問題是否發生在其他內核版本上。因此，如果您
知道如何在一個新啓動的系統上快速重現問題，將使您的工作更加輕鬆。

注意：報告只發生過一次的問題往往是沒有結果的，因爲它們可能是由於宇宙輻射導
致的位翻轉。所以你應該嘗試通過重現問題來排除這種情況，然後再繼續。如果你有
足夠的經驗來區分由於硬體故障引起的一次性錯誤和難以重現的罕見內核問題，可以
忽略這個建議。


穩定版或長期支持內核的回歸？
-----------------------------

    *如果您正面臨穩定版或長期支持版本線的回歸（例如從5.10.4更新到5.10.5時出現
    故障），請查看後文「報告穩定版和長期支持內核線的回歸」小節。*

穩定版和長期支持內核版本線中的回歸是Linux開發人員非常希望解決的問題，這樣的
問題甚至比主線開發分支中的回歸更不應出現，因爲它們會很快影響到很多人。開發人員
希望儘快了解此類問題，因此有一個簡化流程來報告這些問題。注意，使用更新內核版
本線的回歸（比如從5.9.15切換到5.10.5時出現故障）不符合條件。


你需要將問題報告到何處
------------------------

    *定位可能引起問題的驅動程序或內核子系統。找出其開發人員期望的報告的方式
    和位置。注意：大多數情況下不會是bugzilla.kernel.org，因爲問題通常需要通
    過郵件發送給維護人員和公共郵件列表。*

將報告發送給合適的人是至關重要的，因爲Linux內核是一個大項目，大多數開發人員
只熟悉其中的一小部分。例如，相當多的程式設計師只關心一個驅動程序，比如一個WiFi
晶片驅動程序；它的開發人員可能對疏遠的或不相關的「子系統」（如TCP堆棧、
PCIe/PCI子系統、內存管理或文件系統）的內部知識了解很少或完全不了解。

問題在於：Linux內核缺少一個，可以簡單地將問題歸檔並讓需要了解它的開發人員了
解它的，中心化缺陷跟蹤器。這就是爲什麼你必須找到正確的途徑來自己報告問題。
您可以在腳本的幫助下做到這一點（見下文），但它主要針對的是內核開發人員和專
家。對於其他人來說，MAINTAINERS（維護人員）文件是更好的選擇。

如何閱讀MAINTAINERS維護者文件
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

爲了說明如何使用 :ref:`MAINTAINERS <maintainers>` 文件，讓我們假設您的筆記
本電腦中的WiFi在更新內核後突然出現了錯誤行爲。這種情況下可能是WiFi驅動的問
題。顯然，它也可能由於驅動基於的某些代碼，但除非你懷疑有這樣的東西會附著在
驅動程序上。如果真的是其他的問題，驅動程序的開發人員會讓合適的人參與進來。

遺憾的是，沒有通用且簡單的辦法來檢查哪個代碼驅動了特定硬體組件。

在WiFi驅動出現問題的情況下，你可能想查看 ``lspci -k`` 的輸出，因爲它列出了
PCI/PCIe總線上的設備和驅動它的內核模塊::

       [user@something ~]$ lspci -k
       [...]
       3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless Network Adapter (rev 32)
         Subsystem: Bigfoot Networks, Inc. Device 1535
         Kernel driver in use: ath10k_pci
         Kernel modules: ath10k_pci
       [...]

但如果你的WiFi晶片通過USB或其他內部總線連接，這種方法就行不通了。在這種情況
下，您可能需要檢查您的WiFi管理器或 ``ip link`` 的輸出。尋找有問題的網絡接口
的名稱，它可能類似於「wlp58s0」。此名稱可以用來找到驅動它的模塊::

       [user@something ~]$ realpath --relative-to=/sys/module//sys/class/net/wlp58s0/device/driver/module
       ath10k_pci

如果這些技巧不能進一步幫助您，請嘗試在網上搜索如何縮小相關驅動程序或子系統
的範圍。如果你不確定是哪一個：試著猜一下，即使你猜得不好，也會有人會幫助你
的。

一旦您知道了相應的驅動程序或子系統，您就希望在MAINTAINERS文件中搜索它。如果
是「ath10k_pci」，您不會找到任何東西，因爲名稱太具體了。有時你需要在網上尋找
幫助；但在此之前，請嘗試使用一個稍短或修改過的名稱來搜索MAINTAINERS文件，因
爲這樣你可能會發現類似這樣的東西::

       QUALCOMM ATHEROS ATH10K WIRELESS DRIVER
       Mail:          A. Some Human <shuman@example.com>
       Mailing list:  ath10k@lists.infradead.org
       Status:        Supported
       Web-page:      https://wireless.wiki.kernel.org/en/users/Drivers/ath10k
       SCM:           git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git
       Files:         drivers/net/wireless/ath/ath10k/

注意：如果您閱讀在Linux原始碼樹的根目錄中找到的原始維護者文件，則行描述將是
縮寫。例如，「Mail:（郵件）」將是「M:」，「Mailing list:（郵件列表）」將是「L」，
「Status:（狀態）」將是「S:」。此文件頂部有一段解釋了這些和其他縮寫。

首先查看「Status」狀態行。理想情況下，它應該得到「Supported（支持）」或
「Maintained（維護）」。如果狀態爲「Obsolete（過時的）」，那麼你在使用一些過時的
方法，需要轉換到新的解決方案上。有時候，只有在感到有動力時，才會有人爲代碼
提供「Odd Fixes」。如果碰見「Orphan」，你就完全不走運了，因爲再也沒有人關心代碼
了，只剩下這些選項:準備好與問題共存，自己修復它，或者找一個願意修復它的程式設計師。

檢查狀態後，尋找以「bug:」開頭的一行：它將告訴你在哪裡可以找到子系統特定的缺
陷跟蹤器來提交你的問題。上面的例子沒有此行。大多數部分都是這樣，因爲 Linux
內核的開發完全是由郵件驅動的。很少有子系統使用缺陷跟蹤器，且其中只有一部分
依賴於 bugzilla.kernel.org。

在這種以及其他很多情況下，你必須尋找以「Mail:」開頭的行。這些行提到了特定代碼
的維護者的名字和電子郵件地址。也可以查找以「Mailing list:」開頭的行，它告訴你
開發代碼的公共郵件列表。你的報告之後需要通過郵件發到這些地址。另外，對於所有
通過電子郵件發送的問題報告，一定要抄送 Linux Kernel Mailing List（LKML）
<linux-kernel@vger.kernel.org>。在以後通過郵件發送問題報告時，不要遺漏任何
一個郵件列表!維護者都是大忙人，可能會把一些工作留給子系統特定列表上的其他開
發者；而 LKML 很重要，因爲需要一個可以找到所有問題報告的地方。


藉助腳本找到維護者
~~~~~~~~~~~~~~~~~~~~

對於手頭有Linux源碼的人來說，有第二個可以找到合適的報告地點的選擇：腳本
「scripts/get_maintainer.pl」，它嘗試找到所有要聯繫的人。它會查詢MAINTAINERS
文件，並需要用相關原始碼的路徑來調用。對於編譯成模塊的驅動程序，經常可以用
這樣的命令找到::

       $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!'
       drivers/net/wireless/ath/ath10k/ath10k_pci.ko

將其中的部分內容傳遞給腳本::

       $ ./scripts/get_maintainer.pl -f drivers/net/wireless/ath/ath10k*
       Some Human <shuman@example.com> (supporter:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER)
       Another S. Human <asomehuman@example.com> (maintainer:NETWORKING DRIVERS)
       ath10k@lists.infradead.org (open list:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER)
       linux-wireless@vger.kernel.org (open list:NETWORKING DRIVERS (WIRELESS))
       netdev@vger.kernel.org (open list:NETWORKING DRIVERS)
       linux-kernel@vger.kernel.org (open list)

不要把你的報告發給所有的人。發送給維護者，腳本稱之爲「supporter:」；另外抄送
代碼最相關的郵件列表，以及 Linux 內核郵件列表（LKML）。在此例中，你需要將報
告發送給 「Some Human <shuman@example.com>」 ，並抄送
「ath10k@lists.infradead.org」和「linux-kernel@vger.kernel.org」。

注意：如果你用 git 克隆了 Linux 原始碼，你可能需要用--git 再次調用
get_maintainer.pl。腳本會查看提交歷史，以找到最近哪些人參與了相關代碼的編寫，
因爲他們可能會提供幫助。但要小心使用這些結果，因爲它很容易讓你誤入歧途。
例如，這種情況常常會發生在很少被修改的地方（比如老舊的或未維護的驅動程序）：
有時這樣的代碼會在樹級清理期間被根本不關心此驅動程序的開發者修改。


搜索現有報告（第二部分）
--------------------------

    *在缺陷追蹤器或問題相關郵件列表的存檔中徹底搜索可能與您的問題匹配的報告。
    如果找到匹配的報告，請加入討論而不是發送新報告。*

如前所述：報告一個別人已經提出的問題，對每個人來說都是浪費時間，尤其是作爲報告
人的你。這就是爲什麼你應該再次搜索現有的報告。現在你已經知道問題需要報告到哪裡。
如果是郵件列表，那麼一般在 `lore.kernel.org <https://lore.kernel.org/>`_ 可以
找到相應存檔。

但有些列表運行在其他地方。例如前面步驟中當例子的ath10k WiFi驅動程序就是這種
情況。但是你通常可以在網上很容易地找到這些列表的檔案。例如搜索「archive
ath10k@lists.infradead.org」，將引導您到ath10k郵件列表的信息頁，該頁面頂部連結
到其 `列表存檔 <https://lists.infradead.org/pipermail/ath10k/>`_ 。遺憾的是，
這個列表和其他一些列表缺乏搜索其存檔的功能。在這種情況下可以使用常規的網際網路
搜尋引擎，並添加類似「site:lists.infadead.org/pipermail/ath10k/」這
樣的搜索條件，這會把結果限制在該連結中的檔案。

也請進一步搜索網絡、LKML和bugzilla.kernel.org網站。

有關如何搜索以及在找到匹配報告時如何操作的詳細信息，請參閱上面的「搜索現有報告
（第一部分）」。

不要急著完成報告過程的這一步：花30到60分鐘甚至更多的時間可以爲你和其他人節省 /
減少相當多的時間和麻煩。


安裝一個新的內核進行測試
--------------------------

    *除非您已經在運行最新的「主線」Linux內核，否則最好在報告流程前安裝它。在
    某些情況下，使用最新的「穩定版」Linux進行測試和報告也是可以接受的替代方案；
    在合併窗口期間，這實際上可能是最好的方法，但在開發階段最好還是暫停幾天。
    無論你選擇什麼版本，最好使用「普通」構建。忽略這些建議會大大增加您的報告
    被拒絕或忽略的風險。*

正如第一步的詳細解釋中所提到的：與大多數程式設計師一樣，與大多數程式設計師一樣，Linux
內核開發人員不喜歡花時間處理他們維護的原始碼中根本不會發生的問題的報告。這隻
會浪費每個人的時間，尤其是你的時間。這就是爲什麼在報告問題之前，您必須先確認
問題仍然存在於最新的上游代碼中，這符合每個人的利益。您可以忽略此建議，但如前
所述：這樣做會極大地增加問題報告被拒絕或被忽略的風險。

內核「最新上游」的範圍通常指：

 * 安裝一個主線內核；最新的穩定版內核也可以是一個選擇，但大多數時候都最好避免。
   長期支持內核（有時稱爲「LTS內核」）不適合此流程。下一小節將更詳細地解釋所有
   這些。

 * 下一小節描述獲取和安裝這樣一個內核的方法。它還指出了使用預編譯內核是可以的，
   但普通的內核更好，這意味著：它是直接使用從 `kernel.org <https://kernel.org/>`_
   獲得的Linux原始碼構建並且沒有任何方式修改或增強。


選擇適合測試的版本
~~~~~~~~~~~~~~~~~~~~

前往 `kernel.org <https://kernel.org/>`_ 來決定使用哪個版本。忽略那個寫著
「Latest release最新版本」的巨大黃色按鈕，往下看有一個表格。在表格的頂部，你會
看到一行以「mainline」開頭的字樣，大多數情況下它會指向一個版本號類似「5.8-rc2」
的預發布版本。如果是這樣的話，你將需要使用這個主線內核進行測試。不要讓「rc」
嚇到你，這些「開發版內核」實際上非常可靠——而且你已經按照上面的指示做了備份，
不是嗎？

大概每九到十周，「mainline」可能會給你指出一個版本號類似「5.7」的正式版本。如果
碰見這種情況，請考慮暫停報告過程，直到下一個版本的第一個預發布（5.8-rc1）出
現在 `kernel.org <https://kernel.org/>`_ 上。這是因爲 Linux 的開發周期正在
兩周的「合併窗口」內。大部分的改動和所有干擾性的改動都會在這段時間內被合併到
下一個版本中。在此期間使用主線是比較危險的。內核開發者通常也很忙，可能沒有
多餘的時間來處理問題報告。這也是很有可能在合併窗口中應用了許多修改來修復你
所面臨的問題；這就是爲什麼你很快就得用一個新的內核版本重新測試，就像下面「發
布報告後的責任」一節中所述的那樣。

這就是爲什麼要等到合併窗口結束後才去做。但是如果你處理的是一些不應該等待的
東西，則無需這樣做。在這種情況下，可以考慮通過 git 獲取最新的主線內核（見下
文），或者使用 kernel.org 上提供的最新穩定版本。如果 mainline 因爲某些原因
不無法正常工作，那麼使用它也是可以接受的。總的來說：用它來重現問題也比完全
不報告問題要好。

最好避免在合併窗口外使用最新的穩定版內核，因爲所有修復都必須首先應用於主線。
這就是爲什麼檢查最新的主線內核是如此重要：你希望看到在舊版本線修復的任何問題
需要先在主線修復，然後才能得到回傳，這可能需要幾天或幾周。另一個原因是：您
希望的修復對於回傳來說可能太難或太冒險；因此再次報告問題不太可能改變任何事情。

這些方面也部分表明了爲什麼長期支持內核（有時稱爲「LTS內核」）不適合報告流程：
它們與當前代碼的距離太遠。因此，先去測試主線，然後再按流程走：如果主線沒有
出現問題，流程將指導您如何在舊版本線中修復它。

如何獲得新的 Linux 內核
~~~~~~~~~~~~~~~~~~~~~~~~~

你可以使用預編譯或自編譯的內核進行測試；如果你選擇後者，可以使用 git 獲取源
代碼，或者下載其 tar 存檔包。

**使用預編譯的內核** ：這往往是最快速、最簡單、最安全的方法——尤其是在你不熟
悉 Linux 內核的情況下。問題是：發行商或附加存儲庫提供的大多數版本都是從修改
過的Linux原始碼構建的。因此它們不是普通的，通常不適合於測試和問題報告：這些
更改可能會導致您面臨的問題或以某種方式影響問題。

但是如果您使用的是流行的Linux發行版，那麼您就很幸運了：對於大部分的發行版，
您可以在網上找到包含最新主線或穩定版本Linux內核包的存儲庫。使用這些是完全可
以的，只要從存儲庫的描述中確認它們是普通的或者至少接近普通。此外，請確保軟體
包包含kernel.org上提供的最新版本內核。如果這些軟體包的時間超過一周，那麼它們
可能就不合適了，因爲新的主線和穩定版內核通常至少每周發布一次。

請注意，您以後可能需要手動構建自己的內核：有時這是調試或測試修復程序所必需的，
如後文所述。還要注意，預編譯的內核可能缺少在出現panic、Oops、warning或BUG時
解碼內核列印的消息所需的調試符號；如果您計劃解碼這些消息，最好自己編譯內核
（有關詳細信息，請參閱本小節結尾和「解碼失敗信息」小節）。

**使用git** ：熟悉 git 的開發者和有經驗的 Linux 用戶通常最好直接從
`kernel.org 上的官方開發倉庫
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_
中獲取最新的 Linux 內核原始碼。這些很可能比最新的主線預發布版本更新一些。不
用擔心：它們和正式的預發布版本一樣可靠，除非內核的開發周期目前正處於合併窗
口中。不過即便如此，它們也是相當可靠的。

**常規方法** ：不熟悉 git 的人通常最好從 `kernel.org <https://kernel.org/>`_
下載源碼的tar 存檔包。

如何實際構建一個內核並不在這裡描述，因爲許多網站已經解釋了必要的步驟。如果
你是新手，可以考慮按照那些建議使用 ``make localmodconfig`` 來做，它將嘗試獲
取你當前內核的配置，然後根據你的系統進行一些調整。這樣做並不能使編譯出來的
內核更好，但可以更快地編譯。

注意：如果您正在處理來自內核的pannc、Oops、warning或BUG，請在配置內核時嘗試
啓用 CONFIG_KALLSYMS 選項。此外，還可以啓用 CONFIG_DEBUG_KERNEL 和
CONFIG_DEBUG_INFO；後者是相關選項，但只有啓用前者才能開啓。請注意，
CONFIG_DEBUG_INFO 會需要更多儲存空間來構建內核。但這是值得的，因爲這些選項將
允許您稍後精確定位觸發問題的確切代碼行。下面的「解碼失敗信息」一節對此進行了更
詳細的解釋。

但請記住：始終記錄遇到的問題，以防難以重現。發送未解碼的報告總比不報告要好。


檢查「汙染」標誌
----------------

    *確保您剛剛安裝的內核在運行時不會「汙染」自己。*

正如上面已經詳細介紹過的：當發生一些可能會導致一些看起來完全不相關的後續錯
誤的事情時，內核會設置一個「汙染」標誌。這就是爲什麼你需要檢查你剛剛安裝的內
核是否有設置此標誌。如果有的話，幾乎在任何情況下你都需要在報告問題之前先消
除它。詳細的操作方法請看上面的章節。


用新內核重現問題
------------------

    *在您剛剛安裝的內核中復現這個問題。如果它沒有出現，請查看下方只發生在
    穩定版和長期支持內核的問題的說明。*

檢查這個問題是否發生在你剛剛安裝的新 Linux 內核版本上。如果新內核已經修復了，
可以考慮使用此版本線，放棄報告問題。但是請記住，只要它沒有在 `kernel.org
<https://kernel.org/>`_ 的穩定版和長期版（以及由這些版本衍生出來的廠商內核）
中得到修復，其他用戶可能仍然會受到它的困擾。如果你喜歡使用其中的一個，或
者只是想幫助它們的用戶，請前往下面的「報告只發生在較舊內核版本線的問題」一節。


優化復現問題的描述
--------------------

    *優化你的筆記：試著找到並寫出最直接的復現問題的方法。確保最終結果包含所
    有重要的細節，同時讓第一次聽說的人容易閱讀和理解。如果您在此過程中學到
    了一些東西，請考慮再次搜索關於該問題的現有報告。*

過於複雜的報告會讓別人很難理解。因此請儘量找到一個可以直接描述、易於以書面
形式理解的再現方法。包含所有重要的細節，但同時也要儘量保持簡短。

在這在前面的步驟中，你很可能已經了解了一些關於你所面臨的問題的點。利用這些
知識，再次搜索可以轉而加入的現有報告。


解碼失敗信息
-------------

    *如果失敗涉及「panic」、「Oops」、「warning」或「BUG」，請考慮解碼內核日誌以查找
    觸發錯誤的代碼行。*

當內核檢測到內部問題時，它會記錄一些有關已執行代碼的信息。這使得在原始碼中精
確定位觸發問題的行並顯示如何調用它成爲可能。但只有在配置內核時啓用了
CONFIG_DEBUG_INFO 和 CONFIG_KALLSYMS選項時，這種方法才起效。如果已啓用此選項，
請考慮解碼內核日誌中的信息。這將使我們更容易理解是什麼導致了「panic」、「Oops」、
「warning」或「BUG」，從而增加了有人提供修復的機率。

解碼可以通過Linux原始碼樹中的腳本來完成。如果您運行的內核是之前自己編譯的，
這樣這樣調用它::

	[user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh ./linux-5.10.5/vmlinux
	/usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/

如果您運行的是打包好的普通內核，則可能需要安裝帶有調試符號的相應包。然後按以下
方式調用腳本（如果發行版未打包，則可能需要從Linux原始碼獲取）::

	[user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh \
	/usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/

腳本將解碼如下的日誌行，這些日誌行顯示內核在發生錯誤時正在執行的代碼的地址::

	[   68.387301] RIP: 0010:test_module_init+0x5/0xffa [test_module]

解碼之後，這些行將變成這樣::

	[   68.387301] RIP: 0010:test_module_init (/home/username/linux-5.10.5/test-module/test-module.c:16) test_module

在本例中，執行的代碼是從文件「~/linux-5.10.5/test-module/test-module.c」構建的，
錯誤出現在第16行的指令中。

該腳本也會如此解碼以「Call trace」開頭的部分中提到的地址，該部分顯示出現問題的
函數的路徑。此外，腳本還會顯示內核正在執行的代碼部分的彙編輸出。

注意，如果你沒法做到這一點，只需跳過這一步，並在報告中說明原因。如果你幸運的
話，可能無需解碼。如果需要的話，也許有人會幫你做這件事情。還要注意，這只是解
碼內核堆棧跟蹤的幾種方法之一。有時需要採取不同的步驟來檢索相關的詳細信息。
別擔心，如果您碰到的情況需要這樣做，開發人員會告訴您該怎麼做。


對回歸的特別關照
-----------------

    *如果您的問題是回歸問題，請儘可能縮小引入問題時的範圍。*

Linux 首席開發者 Linus Torvalds 認爲 Linux 內核永遠不應惡化，這就是爲什麼他
認爲回歸是不可接受的，並希望看到它們被迅速修復。這就是爲什麼引入了回歸的改
動導致的問題若無法通過其他方式快速解決，通常會被迅速撤銷。因此，報告回歸有
點像「王炸」，會迅速得到修復。但要做到這一點，需要知道導致回歸的變化。通常情
況下，要由報告者來追查罪魁禍首，因爲維護者往往沒有時間或手頭設置不便來自行
重現它。

有一個叫做「二分」的過程可以來尋找變化，這在
「Documentation/translations/zh_TW/admin-guide/bug-bisect.rst」文檔中進行了詳細
的描述，這個過程通常需要你構建十到二十個內核鏡像，每次都嘗試在構建下一個鏡像
之前重現問題。是的，這需要花費一些時間，但不用擔心，它比大多數人想像的要快得多。
多虧了「binary search二進位搜索」，這將引導你在原始碼管理系統中找到導致回歸的提交。
一旦你找到它，就在網上搜索其主題、提交ID和縮短的提交ID（提交ID的前12個字符）。
如果有的話，這將引導您找到關於它的現有報告。

需要注意的是，二分法需要一點竅門，不是每個人都懂得訣竅，也需要相當多的努力，
不是每個人都願意投入。儘管如此，還是強烈建議自己進行一次二分。如果你真的
不能或者不想走這條路，至少要找出是哪個主線內核引入的回歸。比如說從 5.5.15
切換到 5.8.4 的時候出現了一些問題，那麼至少可以嘗試一下相近的所有的主線版本
（5.6、5.7 和 5.8）來檢查它是什麼時候出現的。除非你想在一個穩定版或長期支持
內核中找到一個回歸，否則要避免測試那些編號有三段的版本（5.6.12、5.7.8），因
爲那會使結果難以解釋，可能會讓你的測試變得無用。一旦你找到了引入回歸的主要
版本，就可以放心地繼續報告了。但請記住：在不知道罪魁禍首的情況下，開發人員
是否能夠提供幫助取決於手頭的問題。有時他們可能會從報告中確認是什麼出現了問
題，並能修復它；有時他們可能無法提供幫助，除非你進行二分。

當處理回歸問題時，請確保你所面臨的問題真的是由內核引起的，而不是由其他東西
引起的，如上文所述。

在整個過程中，請記住：只有當舊內核和新內核的配置相似時，問題才算回歸。最好
的方法是：把配置文件（``.config``）從舊的工作內核直接複製到你嘗試的每個新內
核版本。之後運行 ``make oldnoconfig`` 來調整它以適應新版本的需要，而不啓用
任何新的功能，因爲那些功能也可能導致回歸。


撰寫並發送報告
---------------

    *通過詳細描述問題來開始編寫報告。記得包括以下條目：您爲復現而安裝的最新
    內核版本、使用的Linux發行版以及關於如何復現該問題的說明。如果可能，將內
    核構建配置（.config）和 ``dmesg`` 的輸出放在網上的某個地方，並連結到它。
    包含或上傳所有其他可能相關的信息，如Oops的輸出/截圖或來自 ``lspci``
    的輸出。一旦你寫完了這個主要部分，請在上方插入一個正常長度的段落快速概
    述問題和影響。再在此之上添加一個簡單描述問題的句子，以得到人們的閱讀。
    現在給出一個更短的描述性標題或主題。然後就可以像MAINTAINERS文件告訴你的
    那樣發送或提交報告了，除非你在處理一個「高優先級問題」：它們需要按照下面
    「高優先級問題的特殊處理」所述特別關照。*

現在你已經準備好了一切，是時候寫你的報告了。上文前言中連結的三篇文檔對如何
寫報告做了部分解釋。這就是爲什麼本文將只提到一些基本的內容以及 Linux 內核特
有的東西。

有一點是符合這兩類的：你的報告中最關鍵的部分是標題/主題、第一句話和第一段。
開發者經常會收到許多郵件。因此，他們往往只是花幾秒鐘的時間瀏覽一下郵件，然
後再決定繼續下一封或仔細查看。因此，你報告的開頭越好，有人研究並幫助你的機
會就越大。這就是爲什麼你應該暫時忽略他們，先寫出詳細的報告。;-)

每份報告都應提及的事項
~~~~~~~~~~~~~~~~~~~~~~~~

詳細描述你的問題是如何發生在你安裝的新純淨內核上的。試著包含你之前寫的和優
化過的分步說明，概述你和其他人如何重現這個問題；在極少數無法重現的情況下，
儘量描述你做了什麼來觸發它。

還應包括其他人爲了解該問題及其環境而可能需要的所有相關信息。實際需要的東西
在很大程度上取決於具體問題，但有些事項你總是應該包括在內：

 * ``cat /proc/version`` 的輸出，其中包含 Linux 內核版本號和構建時的編譯器。

 * 機器正在運行的 Linux 發行版（ ``hostnamectl | grep 「Operating System「`` ）

 * CPU 和作業系統的架構（ ``uname -mi`` ）

 * 如果您正在處理回歸，並進行了二分，請提及導致回歸的變更的主題和提交ID。

許多情況下，讓讀你報告的人多了解兩件事也是明智之舉：

 * 用於構建 Linux 內核的配置（「.config」文件）

 * 內核的信息，你從 ``dmesg`` 得到的信息寫到一個文件里。確保它以像「Linux
   version 5.8-1 (foobar@example.com) (gcc (GCC) 10.2.1, GNU ld version
   2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020」這樣的行開始，如果沒有，那麼第
   一次啓動階段的重要信息已經被丟棄了。在這種情況下，可以考慮使用
   ``journalctl -b 0 -k`` ；或者你也可以重啓，重現這個問題，然後調用
   ``dmesg`` 。

這兩個文件很大，所以直接把它們放到你的報告中是個壞主意。如果你是在缺陷跟蹤
器中提交問題，那麼將它們附加到工單中。如果你通過郵件報告問題，不要用附件附
上它們，因爲那會使郵件變得太大，可以按下列之一做：

 * 將文件上傳到某個公開的地方（你的網站，公共文件粘貼服務，在
   `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 上創建的工單……），
   並在你的報告中放上連結。理想情況下請使用允許這些文件保存很多年的地方，因
   爲它們可能在很多年後對別人有用；例如 5 年或 10 年後，一個開發者正在修改
   一些代碼，而這些代碼正是爲了修復你的問題。

 * 把文件放在一邊，然後說明你會在他人回復時再單獨發送。只要記得報告發出去後，
   真正做到這一點就可以了。;-)

提供這些東西可能是明智的
~~~~~~~~~~~~~~~~~~~~~~~~~~

根據問題的不同，你可能需要提供更多的背景數據。這裡有一些關於提供什麼比較好
的建議：

 * 如果你處理的是內核的「warning」、「OOPS」或「panic」，請包含它。如果你不能複製
   粘貼它，試著用netconsole網絡終端遠程跟蹤或者至少拍一張屏幕的照片。

 * 如果問題可能與你的電腦硬體有關，請說明你使用的是什麼系統。例如，如果你的
   顯卡有問題，請提及它的製造商，顯卡的型號，以及使用的晶片。如果是筆記本電
   腦，請提及它的型號名稱，但儘量確保意義明確。例如「戴爾 XPS 13」就不很明確，
   因爲它可能是 2012 年的那款，那款除了看起來和現在銷售的沒有什麼不同之外，
   兩者沒有任何共同之處。因此，在這種情況下，要加上準確的型號，例如 2019
   年內推出的 XPS 13 型號爲「9380」或「7390」。像「聯想 Thinkpad T590」這樣的名字
   也有些含糊不清：這款筆記本有帶獨立顯卡和不帶的子型號，所以要儘量找到準確
   的型號名稱或註明主要部件。

 * 說明正在使用的相關軟體。如果你在加載模塊時遇到了問題，你要說明正在使用的
   kmod、systemd 和 udev 的版本。如果其中一個 DRM 驅動出現問題，你要說明
   libdrm 和 Mesa 的版本；還要說明你的 Wayland 合成器或 X-Server 及其驅動。
   如果你有文件系統問題，請註明相應的文件系統實用程序的版本（e2fsprogs,
   btrfs-progs, xfsprogs……）。

 * 從內核中收集可能有用的額外信息。例如， ``lspci -nn`` 的輸出可以幫助別人
   識別你使用的硬體。如果你的硬體有問題，你甚至可以給出 ``sudo lspci -vvv``
   的結果，因爲它提供了組件是如何配置的信息。對於一些問題，可能最好包含
   ``/proc/cpuinfo`` ， ``/proc/ioports`` ， ``/proc/iomem`` ，
   ``/proc/modules`` 或 ``/proc/scsi/scsi`` 等文件的內容。一些子系統還提
   供了收集相關信息的工具。 ``alsa-info.sh`` `就是這樣一個工具，它是音頻/聲
   音子系統開發者提供的  <https://www.alsa-project.org/wiki/AlsaInfo>`_ 。

這些例子應該會給你一些知識點，讓你知道附上什麼數據可能是明智的，但你自己也
要想一想，哪些數據對別人會有幫助。不要太擔心忘記一些東西，因爲開發人員會要
求提供他們需要的額外細節。但從一開始就把所有重要的東西都提供出來，會增加別
人仔細查看的機會。


重要部分：報告的開頭
~~~~~~~~~~~~~~~~~~~~~~

現在你已經準備好了報告的詳細部分，讓我們進入最重要的部分：開頭幾句。現在到
報告的最前面，在你剛才寫的部分之前加上類似「The detailed description:」（詳細
描述）這樣的內容，並在最前面插入兩個新行。現在寫一個正常長度的段落，大致概
述這個問題。去掉所有枯燥的細節，把重點放在讀者需要知道的關鍵部分，以讓人了
解這是怎麼回事；如果你認爲這個缺陷影響了很多用戶，就提一下這點來吸引大家關
注。

做好這一點後，在頂部再插入兩行，寫一句話的摘要，快速解釋報告的內容。之後你
要更加抽象，爲報告寫一個更短的主題/標題。

現在你已經寫好了這部分，請花點時間來優化它，因爲它是你的報告中最重要的部分：
很多人會先讀這部分，然後才會決定是否值得花時間閱讀其他部分。

現在就像 :ref:`MAINTAINERS <maintainers>` 維護者文件告訴你的那樣發送或提交
報告，除非它是前面概述的那些「高優先級問題」之一：在這種情況下，請先閱讀下一
小節，然後再發送報告。

高優先級問題的特殊處理
~~~~~~~~~~~~~~~~~~~~~~~~

高優先級問題的報告需要特殊處理。

**非常嚴重的缺陷** ：確保在主題或工單標題以及第一段中明顯標出 severeness
（非常嚴重的）。

**回歸** ：如果問題是一個回歸，請在郵件的主題或缺陷跟蹤器的標題中添加
[REGRESSION]。如果您沒有進行二分，請至少註明您測試的最新主線版本（比如 5.7）
和出現問題的最新版本（比如 5.8）。如果您成功地進行了二分，請註明導致回歸
的提交ID和主題。也請添加該變更的作者到你的報告中；如果您需要將您的缺陷提交
到缺陷跟蹤器中，請將報告以私人郵件的形式轉發給他，並註明報告提交地點。

**安全問題** ：對於這種問題，你將必須評估：如果細節被公開披露，是否會對其他
用戶產生短期風險。如果不會，只需按照所述繼續報告問題。如果有此風險，你需要
稍微調整一下報告流程。

 * 如果 MAINTAINERS 文件指示您通過郵件報告問題，請不要抄送任何公共郵件列表。

 * 如果你應該在缺陷跟蹤器中提交問題，請確保將工單標記爲「私有」或「安全問題」。
   如果缺陷跟蹤器沒有提供保持報告私密性的方法，那就別想了，把你的報告以私人
   郵件的形式發送給維護者吧。

在這兩種情況下，都一定要將報告發到 MAINTAINERS 文件中「安全聯絡」部分列出的
地址。理想的情況是在發送報告的時候直接抄送他們。如果您在缺陷跟蹤器中提交了
報告，請將報告的文本轉發到這些地址；但請在報告的頂部加上注釋，表明您提交了
報告，並附上工單連結。

更多信息請參見「Documentation/translations/zh_TW/admin-guide/security-bugs.rst」。


發布報告後的責任
------------------

    *等待別人的反應，繼續推進事情，直到你能夠接受這樣或那樣的結果。因此，請
    公開和及時地回應任何詢問。測試提出的修復。積極地測試：至少重新測試每個
    新主線版本的首個候選版本（RC），並報告你的結果。如果出現拖延，就友好地
    提醒一下。如果你沒有得到任何幫助或者未能滿意，請試著自己幫助自己。*

如果你的報告非常優秀，而且你真的很幸運，那麼某個開發者可能會立即發現導致問
題的原因；然後他們可能會寫一個補丁來修復、測試它，並直接發送給主線集成，同
時標記它以便以後回溯到需要它的穩定版和長期支持內核。那麼你需要做的就是回復
一句「Thank you very much」（非常感謝），然後在發布後換上修復好的版本。

但這種理想狀況很少發生。這就是爲什麼你把報告拿出來之後工作才開始。你要做的
事情要視情況而定，但通常會是下面列出的事情。但在深入研究細節之前，這裡有幾
件重要的事情，你需要記住這部分的過程。


關於進一步互動的一般建議
~~~~~~~~~~~~~~~~~~~~~~~~~~

**總是公開回復** ：當你在缺陷跟蹤器中提交問題時，一定要在那裡回復，不要私下
聯繫任何開發者。對於郵件報告，在回復您收到的任何郵件時，總是使用「全部回復」
功能。這包括帶有任何你可能想要添加到你的報告中的額外數據的郵件：進入郵件應
用程序「已發送」文件夾，並在郵件上使用「全部回復」來回復報告。這種方法可以確保
公共郵件列表和其他所有參與者都能及時了解情況；它還能保持郵件線程的完整性，
這對於郵件列表將所有相關郵件歸爲一類是非常重要的。

只有兩種情況不適合在缺陷跟蹤器或「全部回復」中發表評論：

 * 有人讓你私下發東西。

 * 你被告知要發送一些東西，但注意到其中包含需要保密的敏感信息。在這種情況下，
   可以私下發送給要求發送的開發者。但要在工單或郵件中註明你是這麼做的，這
   樣其他人就知道你尊重了這個要求。

**在請求解釋或幫助之前先研究一下** ：在這部分過程中，有人可能會告訴你用尚未
掌握的技能做一些事情。例如你可能會被要求使用一些你從未聽說過的測試工具；或
者你可能會被要求在 Linux 內核原始碼上應用一個補丁來測試它是否有幫助。在某些
情況下，發個回復詢問如何做就可以了。但在走這條路之前，儘量通過在網際網路上搜
索自行找到答案；或者考慮在其他地方詢問建議。比如詢問朋友，或者到你平時常去
的聊天室或論壇發帖諮詢。

**要有耐心** ：如果你真的很幸運，你可能會在幾個小時內收到對你的報告的答覆。
但大多數情況下會花費更多的時間，因爲維護者分散在全球各地，因此可能在不同的
時區——在那裡他們已經享受著遠離鍵盤的夜晚。

一般來說，內核開發者需要一到五個工作日來回復報告。有時會花費更長的時間，因
爲他們可能正忙於合併窗口、其他工作、參加開發者會議，或者只是在享受一個漫長
的暑假。

「高優先級的問題」（見上面的解釋）例外：維護者應該儘快解決這些問題；這就是爲
什麼你應該最多等待一個星期（如果是緊急的事情，則只需兩天），然後再發送友好
的提醒。

有時維護者可能沒有及時回復；有時候可能會出現分歧，例如一個問題是否符合回歸
的條件。在這種情況下，在郵件列表上提出你的顧慮，並請求其他人公開或私下回復
如何繼續推進。如果失敗了，可能應該讓更高級別的維護者介入。如果是 WiFi 驅動，
那就是無線維護者；如果沒有更高級別的維護者，或者其他一切努力都失敗了，那
這可能是一種罕見的、可以讓 Linus Torvalds 參與進來的情況。

**主動測試** ：每當一個新的主線內核版本的第一個預發布版本（rc1）發布的時候，
去檢查一下這個問題是否得到了解決，或者是否有什麼重要的變化。在工單中或在
回復報告的郵件中提及結果（確保所有參與討論的人都被抄送）。這將表明你的承諾
和你願意幫忙。如果問題持續存在，它也會提醒開發者確保他們不會忘記它。其他一
些不定期的重新測試（例如用rc3、rc5 和最終版本）也是一個好主意，但只有在相關
的東西發生變化或者你正在寫什麼東西的時候才報告你的結果。

這些些常規的事情就不說了，我們來談談報告後如何幫助解決問題的細節。

查詢和測試請求
~~~~~~~~~~~~~~~

如果你的報告得到了回復則需履行以下責任：

**檢查與你打交道的人** ：大多數情況下，會是維護者或特定代碼區域的開發人員對
你的報告做出回應。但由於問題通常是公開報告的，所以回復的可能是任何人——包括
那些想要幫忙的人，但最後可能會用他們的問題或請求引導你完全偏離軌道。這很少
發生，但這是快速上網搜搜看你正在與誰互動是明智之舉的許多原因之一。通過這樣
做，你也可以知道你的報告是否被正確的人聽到，因爲如果討論沒有導致滿意的問題
解決方案而淡出，之後可能需要提醒維護者（見下文）。

**查詢數據** ：通常你會被要求測試一些東西或提供更多細節。儘快提供所要求的信
息，因爲你已經得到了可能會幫助你的人的注意，你等待的時間越長就有越可能失去
關注；如果你不在數個工作日內提供信息，甚至可能出現這種結果。

**測試請求** ：當你被要求測試一個診斷補丁或可能的修復時，也要儘量及時測試。
但要做得恰當，一定不要急於求成：混淆事情很容易發生，這會給所有人帶來許多困
惑。例如一個常見的錯誤是以爲應用了一個帶修復的建議補丁，但事實上並沒有。即
使是有經驗的測試人員也會偶爾發生這樣的事情，但當有修復的內核和沒有修復的內
核表現得一樣時，他們大多時候會注意到。

當沒有任何實質性進展時該怎麼辦
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

有些報告不會得到負有相關責任的 Linux 內核開發者的任何反應；或者圍繞這個問題
的討論有所發展，但漸漸淡出，沒有任何實質內容產出。

在這種情況下，要等兩個星期（最好是三個星期）後再發出友好的提醒：也許當你的
報告到達時，維護者剛剛離開鍵盤一段時間，或者有更重要的事情要處理。在寫提醒
信的時候，要善意地問一下，是否還需要你這邊提供什麼來讓事情推進下去。如果報
告是通過郵件發出來的，那就在郵件的第一行回覆你的初始郵件（見上文），其中包
括下方的原始報告的完整引用：這是少數幾種情況下，這樣的「TOFU」（Text Over,
Fullquote Under文字在上，完整引用在下）是正確的做法，因爲這樣所有的收件人都
會以適當的順序立即讓細節到手頭上來。

在提醒之後，再等三周的回覆。如果你仍然沒有得到適當的反饋，你首先應該重新考
慮你的方法。你是否可能嘗試接觸了錯誤的人？是不是報告也許令人反感或者太混亂，
以至於人們決定完全遠離它？排除這些因素的最好方法是：把報告給一兩個熟悉
FLOSS 問題報告的人看，詢問他們的意見。同時徵求他們關於如何繼續推進的建議。
這可能意味著：準備一份更好的報告，讓這些人在你發出去之前對它進行審查。這樣
的方法完全可以；只需說明這是關於這個問題的第二份改進的報告，並附上第一份報
告的連結。

如果報告是恰當的，你可以發送第二封提醒信；在其中詢問爲什麼報告沒有得到任何
回復。第二封提醒郵件的好時機是在新 Linux 內核版本的首個預發布版本（'rc1'）
發布後不久，因爲無論如何你都應該在那個時候重新測試並提供狀態更新（見上文）。

如果第二次提醒的結果又在一周內沒有任何反應，可以嘗試聯繫上級維護者詢問意見：
即使再忙的維護者在這時候也至少應該發過某種確認。

記住要做好失望的準備：理想狀況下維護者最好對每一個問題報告做出回應，但他們
只有義務解決之前列出的「高優先級問題」。所以，如果你得到的回覆是「謝謝你的報告，
我目前有更重要的問題要處理，在可預見的未來沒有時間去研究這個問題」，那請不
要太沮喪。

也有可能在缺陷跟蹤器或列表中進行了一些討論之後，什麼都沒有發生，提醒也無助
於激勵大家進行修復。這種情況可能是毀滅性的，但在 Linux 內核開發中確實會發生。
這些和其他得不到幫助的原因在本文結尾處的「爲什麼有些問題在被報告後沒有得到
任何回應或者仍然沒有修復」中進行了解釋。

如果你沒有得到任何幫助或問題最終沒有得到解決，不要沮喪：Linux 內核是 FLOSS，
因此你仍然可以自己幫助自己。例如，你可以試著找到其他受影響的人，和他們一
起合作來解決這個問題。這樣的團隊可以一起準備一份新的報告，提到團隊有多少人，
爲什麼你們認爲這是應該得到解決的事情。也許你們還可以一起縮小確切原因或引
入回歸的變化，這往往會使修復更容易。而且如果運氣好的話，團隊中可能會有懂點
編程的人，也許能寫出一個修複方案。



「報告穩定版和長期支持內核線的回歸」的參考
------------------------------------------

本小節提供了在穩定版和長期支持內核線中面對回歸時需要執行的步驟的詳細信息。

確保特定版本線仍然受支持
~~~~~~~~~~~~~~~~~~~~~~~~~

    *檢查內核開發人員是否仍然維護你關心的Linux內核版本線：去 kernel.org 的
    首頁，確保此特定版本線的最新版沒有「[EOL]」標記。*

大多數內核版本線只支持三個月左右，因爲延長維護時間會帶來相當多的工作。因此，
每年只會選擇一個版本來支持至少兩年（通常是六年）。這就是爲什麼你需要檢查
內核開發者是否還支持你關心的版本線。

注意，如果 `kernel.org <https://kernel.org/>`_ 在首頁上列出了兩個「穩定」版本，
你應該考慮切換到較新的版本，而忘掉較舊的版本：對它的支持可能很快就會結束。
然後，它將被標記爲「生命周期結束」（EOL）。達到這個程度的版本線仍然會在
`kernel.org <https://kernel.org/>`_ 首頁上被顯示一兩周，但不適合用於測試和
報告。

搜索穩定版郵件列表
~~~~~~~~~~~~~~~~~~~

    *檢查Linux穩定版郵件列表中的現有報告。*

也許你所面臨的問題已經被發現，並且已經或即將被修復。因此，請在 `Linux 穩定
版郵件列表的檔案 <https://lore.kernel.org/stable/>`_ 中搜索類似問題的報告。
如果你找到任何匹配的問題，可以考慮加入討論，除非修復工作已經完成並計劃很快
得到應用。

用最新版本復現問題
~~~~~~~~~~~~~~~~~~~

    *從特定的版本線安裝最新版本作爲純淨內核。確保這個內核沒有被汙染，並且仍
    然存在問題，因爲問題可能已經在那裡被修復了。*

在投入更多時間到這個過程中之前，你要檢查這個問題是否在你關注的版本線的最新
版本中已經得到了修復。這個內核需要是純淨的，在問題發生之前不應該被汙染，正
如上面已經在測試主線的過程中詳細介紹過的一樣。

您是否是第一次注意到供應商內核的回歸？供應商的更改可能會發生變化。你需要重新
檢查排除來這個問題。當您從5.10.4-vendor.42更新到5.10.5-vendor.43時，記錄損壞
的信息。然後在測試了前一段中所述的最新5.10版本之後，檢查Linux 5.10.4的普通版本
是否也可以正常工作。如果問題在那裡出現，那就不符合上游回歸的條件，您需要切換
回主逐步指南來報告問題。

報告回歸
~~~~~~~~~~

    *向Linux穩定版郵件列表發送一個簡短的問題報告(stable@vger.kernel.org)。
    大致描述問題，並解釋如何復現。講清楚首個出現問題的版本和最後一個工作正常
    的版本。然後等待進一步的指示。*

當報告在穩定版或長期支持內核線內發生的回歸（例如在從5.10.4更新到5.10.5時），
一份簡短的報告足以快速報告問題。因此只需要粗略的描述。

但是請注意，如果您能夠指明引入問題的確切版本，這將對開發人員有很大幫助。因此
如果有時間的話，請嘗試使用普通內核找到該版本。讓我們假設發行版發布Linux內核
5.10.5到5.10.8的更新時發生了故障。那麼按照上面的指示，去檢查該版本線中的最新
內核，比如5.10.9。如果問題出現，請嘗試普通5.10.5，以確保供應商應用的補丁不會
干擾。如果問題沒有出現，那麼嘗試5.10.7，然後直到5.10.8或5.10.6（取決於結果）
找到第一個引入問題的版本。在報告中寫明這一點，並指出5.10.9仍然存在故障。

前一段基本粗略地概述了「二分」方法。一旦報告出來，您可能會被要求做一個正確的
報告，因爲它允許精確地定位導致問題的確切更改（然後很容易被恢復以快速修復問題）。
因此如果時間允許，考慮立即進行適當的二分。有關如何詳細信息，請參閱「對回歸的
特別關照」部分和文檔「Documentation/translations/zh_TW/admin-guide/bug-bisect.rst」。


「報告僅在舊內核版本線中發生的問題」的參考
------------------------------------------

本節詳細介紹了如果無法用主線內核重現問題，但希望在舊版本線（又稱穩定版內核和
長期支持內核）中修復問題時需要採取的步驟。

有些修復太複雜
~~~~~~~~~~~~~~~

    *請做好準備，接下來的幾個步驟可能無法在舊版本中解決問題：修復可能太大或
    太冒險，無法移植到那裡。*

即使是微小的、看似明顯的代碼變化，有時也會帶來新的、完全意想不到的問題。穩
定版和長期支持內核的維護者非常清楚這一點，因此他們只對這些內核進行符合
「Documentation/translations/zh_TW/process/stable-kernel-rules.rst」中所列出的
規則的修改。

複雜或有風險的修改不符合條件，因此只能應用於主線。其他的修復很容易被回溯到
最新的穩定版和長期支持內核，但是風險太大，無法集成到舊版內核中。所以要注意
你所希望的修復可能是那些不會被回溯到你所關心的版本線的修復之一。在這種情況
下，你將別無選擇，要麼忍受這個問題，要麼切換到一個較新的 Linux 版本，除非你
想自己把修復補丁應用到你的內核中。

通用準備
~~~~~~~~~~

    *執行上面「報告僅在舊內核版本線中發生的問題」一節中的前三個步驟。*

您需要執行本指南另一節中已經描述的幾個步驟。這些步驟將讓您：

 * 檢查內核開發人員是否仍然維護您關心的Linux內核版本行。

 * 在Linux穩定郵件列表中搜索退出的報告。

 * 檢查最新版本。


檢查代碼歷史和搜索現有的討論
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    *在Linux內核版本控制系統中搜索修復主線問題的更改，因爲它的提交消息可能
    會告訴你修復是否已經計劃好了支持。如果你沒有找到，搜索適當的郵件列表，
    尋找討論此類問題或同行評議可能修復的帖子；然後檢查討論是否認爲修復不適
    合支持。如果支持根本不被考慮，加入最新的討論，詢問是否有可能。*

在許多情況下，你所處理的問題會發生在主線上，但已在主線上得到了解決。修正它
的提交也需要被回溯才能解決這個問題。這就是爲什麼你要搜索它或任何相關討論。

 * 首先嘗試在存放 Linux 內核原始碼的 Git 倉庫中找到修復。你可以通過
   `kernel.org 上的網頁
   <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_
   或 `GitHub 上的鏡像 <https://github.com/torvalds/linux>`_ 來實現；如果你
   有一個本地克隆，你也可以在命令行用 ``git log --grep=<pattern>`` 來搜索。

   如果你找到了修復，請查看提交消息的尾部是否包含了類似這樣的「穩定版標籤」：

          Cc: <stable@vger.kernel.org> # 5.4+

   像上面這行，開發者標記了安全修復可以回傳到 5.4 及以後的版本。大多數情況
   下，它會在兩周內被應用到那裡，但有時需要更長的時間。

 * 如果提交沒有告訴你任何東西，或者你找不到修復，請再找找關於這個問題的討論。
   用你最喜歡的搜尋引擎搜索網絡，以及 `Linux kernel developers mailing
   list 內核開發者郵件列表 <https://lore.kernel.org/lkml/>`_ 的檔案。也可以
   閱讀上面的 `定位導致問題的內核區域` 一節，然後按照說明找到導致問題的子系
   統：它的缺陷跟蹤器或郵件列表存檔中可能有你要找的答案。

 * 如果你看到了一個計劃的修復，請按上所述在版本控制系統中搜索它，因爲提交可
   能會告訴你是否可以進行回溯。

   * 檢查討論中是否有任何跡象表明，該修復程序可能風險太大，無法回溯到你關心
     的版本線。如果是這樣的話，你必須忍受這個問題，或者切換到應用了修復的內
     核版本線。

   * 如果修復的問題未包含穩定版標籤，並且沒有討論過回溯問題，請加入討論：如
     果合適的話，請提及你所面對的問題的版本，以及你希望看到它被修復。


請求建議
~~~~~~~~~

    *前面的步驟之一應該會給出一個解決方案。如果仍未能成功，請向可能引起問題
    的子系統的維護人員詢問建議；抄送特定子系統的郵件列表以及穩定版郵件列表。*

如果前面的三個步驟都沒有讓你更接近解決方案，那麼只剩下一個選擇：請求建議。
在你發給可能是問題根源的子系統的維護者的郵件中這樣做；抄送子系統的郵件列表
以及穩定版郵件列表（stable@vger.kernel.org）。


爲什麼有些問題在報告後沒有任何回應或仍未解決？
===============================================

當向 Linux 開發者報告問題時，要注意只有「高優先級的問題」（回歸、安全問題、嚴
重問題）才一定會得到解決。如果維護者或其他人都失敗了，Linus Torvalds 他自己
會確保這一點。他們和其他內核開發者也會解決很多其他問題。但是要知道，有時他
們也會不能或不願幫忙；有時甚至沒有人發報告給他們。

最好的解釋就是那些內核開發者常常是在業餘時間爲 Linux 內核做出貢獻。內核中的
不少驅動程序都是由這樣的程式設計師編寫的，往往只是因爲他們想讓自己的硬體可以在
自己喜歡的作業系統上使用。

這些程式設計師大多數時候會很樂意修復別人報告的問題。但是沒有人可以強迫他們這樣
做，因爲他們是自願貢獻的。

還有一些情況下，這些開發者真的很想解決一個問題，但卻不能解決：有時他們缺乏
硬體編程文檔來解決問題。這種情況往往由於公開的文檔太簡陋，或者驅動程序是通
過逆向工程編寫的。

業餘開發者遲早也會不再關心某驅動。也許他們的測試硬體壞了，被更高級的玩意取
代了，或者是太老了以至於只能在計算機博物館裡找到。有時開發者根本就不關心他
們的代碼和 Linux 了，因爲在他們的生活中一些不同的東西變得更重要了。在某些情
況下，沒有人願意接手維護者的工作——也沒有人可以被強迫，因爲對 Linux 內核的貢
獻是自願的。然而被遺棄的驅動程序仍然存在於內核中：它們對人們仍然有用，刪除
它們可能導致回歸。

對於那些爲 Linux 內核工作而獲得報酬的開發者來說，情況並沒有什麼不同。這些人
現在貢獻了大部分的變更。但是他們的僱主遲早也會停止關注他們的代碼或者讓程序
員專注於其他事情。例如，硬體廠商主要通過銷售新硬體來賺錢；因此，他們中的不
少人並沒有投入太多時間和精力來維護他們多年前就停止銷售的東西的 Linux 內核驅
動。企業級 Linux 發行商往往持續維護的時間比較長，但在新版本中往往會把對老舊
和稀有硬體的支持放在一邊，以限制範圍。一旦公司拋棄了一些代碼，往往由業餘貢
獻者接手，但正如上面提到的：他們遲早也會放下代碼。

優先級是一些問題沒有被修復的另一個原因，因爲維護者相當多的時候是被迫設置這
些優先級的，因爲在 Linux 上工作的時間是有限的。對於業餘時間或者僱主給予他們
的開發人員用於上游內核維護工作的時間也是如此。有時維護人員也會被報告淹沒，
即使一個驅動程序幾乎完美地工作。爲了不被完全纏住，程式設計師可能別無選擇，只能
對問題報告進行優先級排序而拒絕其中的一些報告。

不過這些都不用太過擔心，很多驅動都有積極的維護者，他們對儘可能多的解決問題
相當感興趣。


結束語
=======

與其他免費/自由&開源軟體（Free/Libre & Open Source Software，FLOSS）相比，
向 Linux 內核開發者報告問題是很難的：這個文檔的長度和複雜性以及字裡行間的內
涵都說明了這一點。但目前就是這樣了。這篇文字的主要作者希望通過記錄現狀來爲
以後改善這種狀況打下一些基礎。