* [PATCH 01/13] docs/zh_TW: process: add researcher-guidelines.rst translation
2026-11-06 11:35 [PATCH 00/13] docs/zh_TW: process: add translations of 13 documents Chen-Yu Yeh
@ 2026-11-06 11:35 ` Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 02/13] docs/zh_TW: process: add cve.rst translation Chen-Yu Yeh
` (11 subsequent siblings)
12 siblings, 0 replies; 14+ messages in thread
From: Chen-Yu Yeh @ 2026-11-06 11:35 UTC (permalink / raw)
To: Alex Shi, Jonathan Corbet
Cc: Weijie Yuan, Dongliang Mu, Yanteng Si, linux-doc, linux-kernel,
Chen-Yu Yeh
Translate Documentation/process/researcher-guidelines.rst into
Traditional Chinese from the current English text, including the
"Surveys" section from commit ad93f083bdb7 ("docs: Add a section on
surveys to the researcher guidelines") and the tech-board list address
from commit 27103dddc2da ("Documentation: update mailing list
addresses"). The zh_CN translation was consulted for wording only.
Keep the three reference link titles and the example commit log in
English, as in the original.
List the new file in the toctree of process/index.rst, after
management-style as in the English index, and drop it from the
TODOList.
update to commit 27103dddc2da ("Documentation: update mailing list
addresses")
Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
.../translations/zh_TW/process/index.rst | 2 +-
.../zh_TW/process/researcher-guidelines.rst | 136 ++++++++++++++++++
2 files changed, 137 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_TW/process/researcher-guidelines.rst
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index bd638264bbe4..fd53103aeb33 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -70,11 +70,11 @@ TODOList:
stable-api-nonsense
stable-kernel-rules
management-style
+ researcher-guidelines
TODOList:
* contribution-maturity-model
-* researcher-guidelines
* generated-content
* coding-assistants
* conclave
diff --git a/Documentation/translations/zh_TW/process/researcher-guidelines.rst b/Documentation/translations/zh_TW/process/researcher-guidelines.rst
new file mode 100644
index 000000000000..ded8aaa0a843
--- /dev/null
+++ b/Documentation/translations/zh_TW/process/researcher-guidelines.rst
@@ -0,0 +1,136 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_TW.rst
+
+:Original: Documentation/process/researcher-guidelines.rst
+
+.. _tw_researcher_guidelines:
+
+研究人員指南
+++++++++++++
+
+Linux 核心社群歡迎對 Linux 核心、產生核心所涉及的活動，以及其開發過程中的
+任何其他副產品進行透明的研究。Linux 從這類研究中獲益良多，而 Linux 的大多
+數面向也都以某種形式受到研究的推動。
+
+社群非常感謝研究人員在公開研究結果之前先分享初步發現，特別是涉及安全性的
+研究。及早參與既有助於提升研究的品質，也有助於 Linux 從研究中獲得改進。無
+論如何，都建議與社群分享已發表研究的開放取用（open access）版本。
+
+本文件旨在說明 Linux 核心社群在進行這類研究時，認為哪些做法可以接受、哪些
+不可接受。這類研究及相關活動至少應遵循標準的研究倫理規範。關於一般的研究
+倫理、科技倫理，特別是針對開發者社群之研究的更多背景資訊，請參閱：
+
+* `History of Research Ethics <https://www.unlv.edu/research/ORI-HSR/history-ethics>`_
+* `IEEE Ethics <https://www.ieee.org/about/ethics/index.html>`_
+* `Developer and Researcher Views on the Ethics of Experiments on Open-Source Projects <https://arxiv.org/pdf/2112.13217.pdf>`_
+
+Linux 核心社群期望每一位與本專案互動的人，都是本著善意參與，為了讓 Linux
+變得更好。歡迎對 Linux 核心社群產出的任何公開成果（包括但不限於原始程式碼）
+進行研究，但以開發者為對象的研究必須明確採取選擇加入（opt-in）的方式。
+
+完全基於公開來源（包括公開郵件列表上的貼文，以及公開儲存庫中的提交）的被
+動研究，顯然是允許的。不過，如同任何研究一樣，仍然必須遵循標準的倫理規範。
+
+然而，針對開發者行為的主動研究，必須在取得相關開發者個人的明確同意，並向
+他們完整揭露的情況下進行。未經同意，不得與開發者互動或對他們進行實驗；這
+同樣是標準的研究倫理。
+
+問卷調查
+========
+
+研究經常採取向維護者或貢獻者發送問卷調查的形式。不過，一般而言，核心社群
+從這些問卷調查中獲得的價值很少。核心開發流程之所以能夠運作，是因為每位開
+發者都能從自己的參與中受益，即使是與目標不同的其他人一起工作也是如此。然
+而，回覆問卷調查是加諸在忙碌開發者身上的單向要求，對他們自己或整個核心社
+群都沒有相對應的好處。因此，我們不鼓勵這種研究方法。
+
+核心社群成員收到的電子郵件已經太多了，很可能會把問卷調查的請求視為又一項
+占用他們時間的要求。發送這類請求會剝奪社群寶貴的貢獻者時間，而且不太可能
+得到具有統計意義的回應。
+
+作為替代方案，研究人員應該考慮參加開發者活動，舉辦說明研究專案及其對參與
+者之好處的場次，並在那裡直接與社群互動。這樣獲得的資訊會比電子郵件問卷調
+查豐富得多，而社群也能從你的見解中學習並因此受益。
+
+補丁
+====
+
+說明一下：向開發者發送補丁 *確實是* 與他們互動，但他們已經同意接收
+*善意的貢獻*。他們並未同意接收刻意帶有缺陷或漏洞的補丁，也未同意在討論中
+被提供誤導性的資訊。這類交流可能對開發者造成傷害（例如耗費時間、精力和士
+氣），也會損害專案：它會侵蝕整個開發者社群對該貢獻者（以及該貢獻者所屬組
+織整體）的信任，破壞為貢獻者提供建設性回饋的努力，並使終端使用者暴露於軟
+體缺陷的風險之中。
+
+研究人員參與 Linux 本身的開發，與其他任何人一樣，都是受到歡迎與鼓勵的。研
+究 Linux 程式碼是常見的做法，尤其是在開發或執行能產生具體可行結果的分析工
+具時。
+
+在與開發者社群互動時，發送補丁向來是發揮影響力的最佳方式。Linux 已知的缺
+陷已經夠多了——更有幫助的是經過審查的修復。在貢獻之前，請仔細閱讀相關文件：
+
+* Documentation/process/development-process.rst
+* Documentation/process/submitting-patches.rst
+* Documentation/admin-guide/reporting-issues.rst
+* Documentation/process/security-bugs.rst
+
+然後發送補丁（包括附有下列所有細節的提交日誌），並跟進其他開發者的任何回饋。
+
+發送由研究產生的補丁時，提交日誌至少應包含以下細節，讓開發者有適當的背景
+來理解這項貢獻。請回答：
+
+* 發現的具體問題是什麼？
+* 在執行中的系統上，如何觸發這個問題？
+* 遇到這個問題會對系統造成什麼影響？
+* 問題是如何發現的？請具體說明所使用的任何測試、靜態或動態分析程式，以及
+ 用於完成這項工作的任何其他工具或方法的細節。
+* 問題是在哪個 Linux 版本上發現的？強烈建議使用最新的發布版本或近期的
+ linux-next 分支（請參閱 Documentation/process/howto.rst）。
+* 為了修復問題做了哪些修改？為什麼認為這些修改是正確的？
+* 這項修改是如何進行建置測試和執行期測試的？
+* 這項修改修復的是之前的哪一個提交？如文件所述，這應該寫在 "Fixes:" 標籤中。
+* 還有誰審查過這個補丁？這應該寫在適當的 "Reviewed-by:" 標籤中；請見下文。
+
+例如::
+
+ From: Author <author@email>
+ Subject: [PATCH] drivers/foo_bar: Add missing kfree()
+
+ The error path in foo_bar driver does not correctly free the allocated
+ struct foo_bar_info. This can happen if the attached foo_bar device
+ rejects the initialization packets sent during foo_bar_probe(). This
+ would result in a 64 byte slab memory leak once per device attach,
+ wasting memory resources over time.
+
+ This flaw was found using an experimental static analysis tool we are
+ developing, LeakMagic[1], which reported the following warning when
+ analyzing the v5.15 kernel release:
+
+ path/to/foo_bar.c:187: missing kfree() call?
+
+ Add the missing kfree() to the error path. No other references to
+ this memory exist outside the probe function, so this is the only
+ place it can be freed.
+
+ x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC
+ 11.2 show no new warnings, and LeakMagic no longer warns about this
+ code path. As we don't have a FooBar device to test with, no runtime
+ testing was able to be performed.
+
+ [1] https://url/to/leakmagic/details
+
+ Reported-by: Researcher <researcher@email>
+ Fixes: aaaabbbbccccdddd ("Introduce support for FooBar")
+ Signed-off-by: Author <author@email>
+ Reviewed-by: Reviewer <reviewer@email>
+
+如果你是第一次貢獻，建議在把補丁發布到公開列表之前，先私下請其他人審查補
+丁本身。（如果有人明確告訴過你，你的補丁需要更仔細的內部審查，這就是必要
+的。）最終的補丁中應包含這些人的 "Reviewed-by" 標籤。找一位熟悉 Linux 貢獻
+流程的開發者，尤其是你所屬組織內部的人，請他們在補丁發送到公開郵件列表之
+前協助審查，往往能顯著提升最終補丁的品質，從而減輕其他開發者的負擔。
+
+如果找不到人在內部審查補丁，而你需要協助尋找這樣的人，或者你對本文件以及
+開發者社群的期望有任何其他問題，請聯絡技術諮詢委員會（Technical Advisory
+Board）的私人郵件列表：<tech-board@groups.linuxfoundation.org>。
--
2.43.0
^ permalink raw reply [flat|nested] 14+ messages in thread* [PATCH 02/13] docs/zh_TW: process: add cve.rst translation
2026-11-06 11:35 [PATCH 00/13] docs/zh_TW: process: add translations of 13 documents Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 01/13] docs/zh_TW: process: add researcher-guidelines.rst translation Chen-Yu Yeh
@ 2026-11-06 11:35 ` Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 03/13] docs/zh_TW: process: add applying-patches.rst translation Chen-Yu Yeh
` (10 subsequent siblings)
12 siblings, 0 replies; 14+ messages in thread
From: Chen-Yu Yeh @ 2026-11-06 11:35 UTC (permalink / raw)
To: Alex Shi, Jonathan Corbet
Cc: Weijie Yuan, Dongliang Mu, Yanteng Si, linux-doc, linux-kernel,
Chen-Yu Yeh
Translate Documentation/process/cve.rst into Traditional Chinese from
the current English text. The zh_CN translation was consulted for
wording only.
List the new file in the toctree of process/index.rst, after
security-bugs as in the English index, and drop it from the TODOList.
update to commit 5928d411557e ("Documentation: Document the Linux
Kernel CVE process")
Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
.../translations/zh_TW/process/cve.rst | 90 +++++++++++++++++++
.../translations/zh_TW/process/index.rst | 2 +-
2 files changed, 91 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_TW/process/cve.rst
diff --git a/Documentation/translations/zh_TW/process/cve.rst b/Documentation/translations/zh_TW/process/cve.rst
new file mode 100644
index 000000000000..186cd47f5474
--- /dev/null
+++ b/Documentation/translations/zh_TW/process/cve.rst
@@ -0,0 +1,90 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_TW.rst
+
+:Original: Documentation/process/cve.rst
+
+====
+CVEs
+====
+
+Common Vulnerabilities and Exposure（CVE®）編號的設計初衷，是提供一種
+明確的方式，來識別、定義與編錄公開披露的安全漏洞。隨著時間推移，CVE 編號
+對核心專案的用處逐漸降低，而且經常以不恰當的方式、出於不恰當的理由被分配。
+因此，核心開發社群一向傾向迴避它們。然而，要求分配 CVE 及其他形式安全識別
+碼的壓力持續不斷，加上核心社群以外的個人與公司持續濫用，已經清楚顯示核心
+社群應該掌控這些分配。
+
+Linux 核心開發團隊確實有能力為潛在的 Linux 核心安全問題分配 CVE。這項分配
+獨立於 :doc:`一般的 Linux 核心安全缺陷回報流程 <../process/security-bugs>`。
+
+所有已分配給 Linux 核心的 CVE 列表，可以在 linux-cve 郵件列表的存檔中找到，
+見 https://lore.kernel.org/linux-cve-announce/ 。若要收到已分配 CVE 的
+通知，請 `訂閱 <https://subspace.kernel.org/subscribing.html>`_ 該郵件列表。
+
+流程
+====
+
+作為一般穩定版發布流程的一部分，可能構成安全問題的核心變更，會由負責 CVE
+編號分配的開發者辨識出來，並自動為其分配 CVE 編號。這些分配會以公告的形式，
+頻繁地發布在 linux-cve-announce 郵件列表上。
+
+注意，由於 Linux 核心在系統中所處的層級，幾乎任何缺陷都可能被利用來危害
+核心的安全性，但在修復缺陷時，被利用的可能性往往並不明顯。因此，CVE 分配
+團隊採取過度謹慎的做法，會為他們辨識出的任何缺陷修復分配 CVE 編號。這也
+說明了為什麼 Linux 核心團隊發布的 CVE 數量看起來如此之多。
+
+如果 CVE 分配團隊漏掉了某個特定的修復，而任何使用者認為它應該被分配 CVE，
+請寄送電子郵件至 <cve@kernel.org>，那裡的團隊會與你一起處理。請注意，任何
+潛在的安全問題都不應寄到這個信箱，它「僅」用於為已經進入已發布核心樹的修復
+分配 CVE。如果你認為自己發現了一個尚未修復的安全問題，請依照
+:doc:`一般的 Linux 核心安全缺陷回報流程 <../process/security-bugs>` 處理。
+
+Linux 核心中尚未修復的安全問題不會被自動分配 CVE；只有在修復已經可用並套用
+到穩定核心樹之後，才會自動進行分配，並以原始修復的 git commit id 來追蹤。
+如果有人希望在問題透過提交解決之前就分配 CVE，請聯絡核心 CVE 分配團隊
+<cve@kernel.org>，從他們保留的一批識別碼中取得一個。
+
+對於 Stable/LTS 核心團隊目前未積極支援的核心版本中發現的任何問題，都不會
+分配 CVE。目前支援的核心分支列表可在 https://kernel.org/releases.html 找到。
+
+對已分配 CVE 的爭議
+===================
+
+對特定核心變更所分配的 CVE 提出爭議或加以修改的權限，僅屬於受影響的相關
+子系統的維護者。這項原則確保了漏洞回報的高度準確性與可問責性。只有對該子
+系統具備深厚專業知識與深入了解的人，才能有效評估所回報漏洞的有效性與範圍，
+並判定其適當的 CVE 認定。任何在此指定權限之外修改或爭議 CVE 的嘗試，都可
+能導致混亂、不準確的回報，最終危及系統。
+
+無效的 CVE
+==========
+
+如果某個安全問題出現在僅由某個 Linux 發行版支援的 Linux 核心中，原因是該
+發行版所做的變更，或是該發行版支援的核心版本已不再屬於 kernel.org 支援的
+版本之一，那麼 Linux 核心 CVE 團隊無法分配 CVE，必須向該 Linux 發行版本身
+申請。
+
+任何由核心 CVE 分配團隊以外的團體，針對積極支援中的核心版本分配給 Linux
+核心的 CVE，都不應被視為有效的 CVE。請通知核心 CVE 分配團隊
+<cve@kernel.org>，讓他們能透過 CNA 補救流程使這類條目失效。
+
+特定 CVE 的適用性
+=================
+
+由於 Linux 核心可以用許多不同的方式使用，外部使用者存取它的方式也有很多種，
+甚至完全無法存取，因此任何特定 CVE 的適用性應由 Linux 的使用者自行判斷，
+而不是由 CVE 分配團隊決定。請不要聯絡我們，試圖確認任何特定 CVE 的適用性。
+
+此外，由於原始程式碼樹非常龐大，而任何一個系統都只會使用其中一小部分，所有
+Linux 使用者都應該了解，大量已分配的 CVE 與他們的系統並不相關。
+
+簡而言之，我們不知道你的使用情境，也不知道你使用了核心的哪些部分，因此我們
+無從判斷特定的 CVE 是否與你的系統相關。
+
+一如既往，最好採用所有已發布的核心變更，因為它們是由許多社群成員作為一個
+統一的整體一起測試過的，而不是一個個單獨挑選（cherry-pick）出來的變更。
+另外也請注意，對於許多缺陷來說，整體問題的解決方案並不在單一變更中，而是
+由許多層層疊加的修復共同構成。理想情況下，所有問題的所有修復都會被分配
+CVE，但有時我們會沒有注意到某些修復，因此請假設某些沒有分配 CVE 的變更
+也可能值得採用。
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index fd53103aeb33..80fff2203e55 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -90,13 +90,13 @@ TODOList:
debugging/index
security-bugs
+ cve
embargoed-hardware-issues
TODOList:
* handling-regressions
* threat-model
-* cve
維護者資訊
----------
--
2.43.0
^ permalink raw reply [flat|nested] 14+ messages in thread* [PATCH 03/13] docs/zh_TW: process: add applying-patches.rst translation
2026-11-06 11:35 [PATCH 00/13] docs/zh_TW: process: add translations of 13 documents Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 01/13] docs/zh_TW: process: add researcher-guidelines.rst translation Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 02/13] docs/zh_TW: process: add cve.rst translation Chen-Yu Yeh
@ 2026-11-06 11:35 ` Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 04/13] docs/zh_TW: process: add maintainer-pgp-guide.rst translation Chen-Yu Yeh
` (9 subsequent siblings)
12 siblings, 0 replies; 14+ messages in thread
From: Chen-Yu Yeh @ 2026-11-06 11:35 UTC (permalink / raw)
To: Alex Shi, Jonathan Corbet
Cc: Weijie Yuan, Dongliang Mu, Yanteng Si, linux-doc, linux-kernel,
Chen-Yu Yeh
Translate Documentation/process/applying-patches.rst into Traditional
Chinese from the current English text, including the "Normal patches"
and "Incremental patches" subsections of "The 5.x.y kernels". The
zh_CN translation was consulted for wording only.
List the new file in the toctree of process/index.rst, after
email-clients as in the English index, and drop it from the TODOList.
update to commit fa04150b8ef7 ("Documentation: describe how to apply
incremental stable patches")
Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
.../zh_TW/process/applying-patches.rst | 392 ++++++++++++++++++
.../translations/zh_TW/process/index.rst | 2 +-
2 files changed, 393 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_TW/process/applying-patches.rst
diff --git a/Documentation/translations/zh_TW/process/applying-patches.rst b/Documentation/translations/zh_TW/process/applying-patches.rst
new file mode 100644
index 000000000000..5dcda7abd3ad
--- /dev/null
+++ b/Documentation/translations/zh_TW/process/applying-patches.rst
@@ -0,0 +1,392 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_TW.rst
+
+:Original: Documentation/process/applying-patches.rst
+
+.. _tw_applying_patches:
+
+將修補程式套用到 Linux 核心
++++++++++++++++++++++++++++
+
+原作者：
+ Jesper Juhl，2005 年 8 月
+
+.. note::
+
+ 本文件已經過時。在大多數情況下，你幾乎一定會想改用 Git，而不是手動
+ 執行 ``patch``。
+
+Linux 核心郵件列表上經常有人問：要如何把修補程式套用到核心？更具體地
+說，針對眾多樹或分支之一所製作的修補程式，應該套用到哪個基礎核心上？
+希望本文件能為你解答這些問題。
+
+除了說明如何套用與撤銷修補程式，本文件也會簡要介紹不同的核心樹（並舉例
+說明如何套用各個核心樹特有的修補程式）。
+
+
+什麼是修補程式？
+================
+
+修補程式是一份小型文字文件，記錄原始碼樹兩個不同版本之間的差異。修補
+程式由 ``diff`` 程式產生。
+
+要正確套用修補程式，你需要知道它是以哪個版本為基礎產生的，以及它會把
+原始碼樹變成哪個新版本。這兩項資訊應該都記錄在修補程式檔案的中繼資料
+中，或者可以從檔名推斷出來。
+
+
+如何套用或撤銷修補程式？
+========================
+
+使用 ``patch`` 程式套用修補程式。patch 程式會讀取 diff 檔（或修補程式
+檔），並依照其中的描述修改原始碼樹。
+
+Linux 核心的修補程式是以存放核心原始碼目錄的上層目錄為基準產生的。
+
+這表示修補程式檔案中的檔案路徑，會包含產生修補程式時所用的核心原始碼
+目錄名稱（或「a/」與「b/」之類的其他目錄名稱）。
+
+這個名稱不太可能與你本機上的核心原始碼目錄名稱相同（不過，對於沒有標示
+版本的修補程式，它常常是判斷其基礎版本的有用資訊），所以你應該先切換到
+核心原始碼目錄，套用修補程式時再去掉修補程式檔案中檔名路徑的第一個部分
+（``patch`` 的 ``-p1`` 參數就是做這件事）。
+
+要撤銷先前套用的修補程式，請對 patch 使用 -R 參數。所以，如果你是這樣
+套用修補程式的::
+
+ patch -p1 < ../patch-x.y.z
+
+就可以這樣撤銷（復原）它::
+
+ patch -R -p1 < ../patch-x.y.z
+
+
+如何把修補程式檔或 diff 檔交給 ``patch``？
+==========================================
+
+這件事（就像在 Linux 和其他類 UNIX 作業系統上常見的那樣）有好幾種不同
+的做法。
+
+在下面所有的範例中，我都用以下語法，透過標準輸入（stdin）把（未壓縮的）
+檔案交給 patch::
+
+ patch -p1 < path/to/patch-x.y.z
+
+如果你只是想照著下面的範例操作，不想知道 patch 的其他用法，那麼本節讀到
+這裡就可以了。
+
+patch 也可以透過 -i 參數取得要使用的檔案名稱，像這樣::
+
+ patch -p1 -i path/to/patch-x.y.z
+
+如果你的修補程式檔案是用 gzip 或 xz 壓縮的，而你不想在套用前先解壓縮，
+可以改用這種方式把它交給 patch::
+
+ xzcat path/to/patch-x.y.z.xz | patch -p1
+ bzcat path/to/patch-x.y.z.gz | patch -p1
+
+如果你想在套用前先手動解壓縮修補程式檔案（下面的範例都假設你已經這樣
+做了），只要對檔案執行 gunzip 或 xz 即可，像這樣::
+
+ gunzip patch-x.y.z.gz
+ xz -d patch-x.y.z.xz
+
+這樣會留下一個純文字的 patch-x.y.z 檔案，你可以依自己的喜好，透過標準
+輸入或 ``-i`` 參數把它交給 patch。
+
+patch 還有幾個好用的參數：``-s`` 讓 patch 除了錯誤以外不輸出任何訊息，
+可以避免錯誤訊息太快捲出螢幕；``--dry-run`` 讓 patch 只列出將會發生的
+事情，而不實際做任何修改。最後，``--verbose`` 讓 patch 輸出更多關於
+處理過程的資訊。
+
+
+套用修補程式時的常見錯誤
+========================
+
+patch 套用修補程式檔案時，會用各種方式檢查檔案是否合理。
+
+檢查檔案看起來是否像有效的修補程式檔案，以及檢查要修改的部分周圍的程式碼
+是否與修補程式提供的上下文相符，只是 patch 所做的兩項基本檢查。
+
+如果 patch 遇到看起來不太對的地方，它有兩種選擇：拒絕套用變更並中止，
+或者設法稍作調整，讓修補程式能夠套用。
+
+patch 會嘗試修正的「不太對」的情況之一，是上下文全部相符、要修改的行也
+相符，但行號不同。舉例來說，如果修補程式修改的是檔案中間的內容，而檔案
+開頭附近因為某些原因增加或刪除了幾行，就會發生這種情況。此時一切看起來
+都沒問題，只是位置上下移動了一些，patch 通常會調整行號並套用修補程式。
+
+每當 patch 必須稍微修改修補程式才能套用時，它會告訴你修補程式是經過
+**fuzz** （模糊比對）才套用的。你應該對這類變更保持警覺，因為雖然 patch
+很可能處理正確，但它並不/總是/正確，結果有時會是錯的。
+
+當 patch 遇到無法用 fuzz 修正的變更時，會直接拒絕它，並留下一個副檔名為
+``.rej`` 的檔案（拒絕檔）。你可以閱讀這個檔案，確切了解哪項變更無法套用，
+以便視需要手動修正。
+
+如果你的核心原始碼沒有套用任何第三方修補程式，只套用了來自 kernel.org
+的修補程式，而且套用順序正確，也沒有自行修改過原始碼檔案，那麼你應該
+永遠不會看到 patch 輸出 fuzz 或拒絕的訊息。如果你還是看到了這類訊息，
+那麼你的本機原始碼樹或修補程式檔案很有可能已經以某種方式損毀。此時你
+大概應該試著重新下載修補程式；如果問題依舊，建議你從 kernel.org 重新
+完整下載一份全新的原始碼樹，從頭開始。
+
+下面進一步看看 patch 可能輸出的幾種訊息。
+
+如果 patch 停下來並顯示 ``File to patch:`` 提示，表示 patch 找不到要修改
+的檔案。最可能的原因是你忘了指定 -p1，或者你所在的目錄不對。比較少見的
+情況是，你會遇到需要用 ``-p0`` 而不是 ``-p1`` 套用的修補程式（閱讀修補
+程式檔案應該就能看出是否如此；如果是，這是製作修補程式的人的錯誤，但並
+不致命）。
+
+如果你看到 ``Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines).``
+或類似的訊息，表示 patch 必須調整變更的位置（在這個例子中，它必須把變更
+從預期的位置移動 7 行才能套用）。
+
+產生的檔案不一定正確，要看檔案與預期不同的原因而定。
+
+當你嘗試套用一個以不同核心版本產生的修補程式，而不是以你要修改的版本
+產生的修補程式時，經常會發生這種情況。
+
+如果你看到像 ``Hunk #3 FAILED at 2387.`` 這樣的訊息，表示修補程式無法
+正確套用，patch 程式也無法透過 fuzz 完成套用。這會產生一個 ``.rej`` 檔，
+其中包含導致修補程式失敗的變更，還會產生一個 ``.orig`` 檔，顯示無法修改
+的原始內容。
+
+如果你看到
+``Reversed (or previously applied) patch detected! Assume -R? [n]``
+，表示 patch 偵測到修補程式中的變更似乎已經存在。
+
+如果你確實之前已經套用過這個修補程式，只是不小心又套用了一次，那就回答
+[n]o 並中止這個修補程式。如果你之前套用過這個修補程式，本來就打算撤銷
+它，只是忘了指定 -R，那麼可以在這裡回答 [**y**]es，讓 patch 替你撤銷。
+
+如果修補程式的製作者在製作時把來源目錄與目的目錄弄反了，也會發生這種
+情況；此時撤銷修補程式實際上就是套用它。
+
+類似 ``patch: **** unexpected end of file in patch`` 或
+``patch unexpectedly ends in middle of line`` 的訊息，表示 patch 完全
+無法理解你交給它的檔案。可能是你下載的檔案已損壞、你沒有先解壓縮就把
+壓縮過的修補程式檔案交給 patch，或者你使用的修補程式檔案在傳遞途中被
+某個郵件用戶端或郵件傳輸代理弄亂了，例如把一行過長的內容拆成兩行。通常
+只要把被拆開的兩行重新接（串接）起來，就能輕鬆解決這類警告。
+
+如前所述，如果你把 kernel.org 的修補程式套用到版本正確、未經修改的原始碼
+樹上，這些錯誤應該永遠不會發生。所以，如果你在套用 kernel.org 的修補程式
+時遇到這些錯誤，大概就該認定你的修補程式檔案或原始碼樹已經損壞；建議你
+重新下載完整的核心樹和要套用的修補程式，從頭開始。
+
+
+除了 ``patch`` 還有其他選擇嗎？
+===============================
+
+
+有的。
+
+你可以使用 ``interdiff`` 程式 (http://cyberelk.net/tim/patchutils/)
+產生一個代表兩個修補程式之間差異的修補程式，然後套用這個結果。
+
+這樣就能一步從 5.7.2 之類的版本更新到 5.7.3。interdiff 的 -z 選項甚至
+可以讓你直接傳入以 gzip 或 bzip2 壓縮的修補程式，不必使用 zcat 或 bzcat，
+也不必手動解壓縮。
+
+以下是一步從 5.7.2 更新到 5.7.3 的做法::
+
+ interdiff -z ../patch-5.7.2.gz ../patch-5.7.3.gz | patch -p1
+
+雖然 interdiff 可以幫你省下一兩個步驟，但一般仍建議你執行那些額外的步驟，
+因為 interdiff 在某些情況下會出錯。
+
+另一個選擇是 ``ketchup``，它是一個自動下載並套用修補程式的 Python 指令碼
+(https://www.selenic.com/ketchup/)。
+
+其他好用的工具還有：diffstat，顯示修補程式所做變更的摘要；lsdiff，簡短
+列出修補程式檔案影響到的檔案，並可選擇一併顯示每段修補程式的起始行號；
+以及 grepdiff，列出修補程式中內容符合指定正規表示式的部分所修改的檔案。
+
+
+可以從哪裡下載修補程式？
+========================
+
+修補程式可以在 https://kernel.org/ 取得。
+首頁有最新修補程式的連結，但它們也各自有固定的存放位置。
+
+5.x.y（-stable）與 5.x 修補程式位於
+
+ https://www.kernel.org/pub/linux/kernel/v5.x/
+
+5.x.y 增量修補程式位於
+
+ https://www.kernel.org/pub/linux/kernel/v5.x/incr/
+
+-rc 修補程式不存放在網頁伺服器上，而是從 git 標籤按需產生，例如
+
+ https://git.kernel.org/torvalds/p/v5.1-rc1/v5.0
+
+穩定版的 -rc 修補程式位於
+
+ https://www.kernel.org/pub/linux/kernel/v5.x/stable-review/
+
+
+5.x 核心
+========
+
+這些是 Linus 發布的基礎穩定版本。版本號最大的就是最新的版本。
+
+如果發現迴歸或其他嚴重缺陷，就會在這個基礎版本之上發布 -stable 修正
+修補程式（見下文）。一旦新的 5.x 基礎核心發布，也會提供一個修補程式，
+內容是前一個 5.x 核心與新核心之間的差異。
+
+要套用從 5.6 更新到 5.7 的修補程式，請依照下列步驟操作（請注意，這類
+修補程式 **不能** 套用在 5.x.y 核心之上，而是套用在基礎 5.x 核心之上；
+如果你要從 5.x.y 更新到 5.x+1，必須先撤銷 5.x.y 修補程式）。
+
+以下是一些範例::
+
+ # moving from 5.6 to 5.7
+
+ $ cd ~/linux-5.6 # change to kernel source dir
+ $ patch -p1 < ../patch-5.7 # apply the 5.7 patch
+ $ cd ..
+ $ mv linux-5.6 linux-5.7 # rename source dir
+
+ # moving from 5.6.1 to 5.7
+
+ $ cd ~/linux-5.6.1 # change to kernel source dir
+ $ patch -p1 -R < ../patch-5.6.1 # revert the 5.6.1 patch
+ # source dir is now 5.6
+ $ patch -p1 < ../patch-5.7 # apply new 5.7 patch
+ $ cd ..
+ $ mv linux-5.6.1 linux-5.7 # rename source dir
+
+
+5.x.y 核心
+==========
+
+版本號有三段數字的核心是 -stable 核心。它們包含針對某個 5.x 核心中發現
+的安全問題或重大迴歸所做的（較）小型關鍵修正。
+
+對於想要最新穩定核心、又無意幫忙測試開發版或實驗版的使用者，建議使用
+這個分支。
+
+如果沒有可用的 5.x.y 核心，那麼版本號最大的 5.x 核心就是目前的穩定核心。
+
+-stable 團隊同時提供一般修補程式與增量修補程式。以下說明如何套用這些
+修補程式。
+
+一般修補程式
+~~~~~~~~~~~~
+
+這類修補程式不是增量的，也就是說，例如 5.7.3 修補程式並不是套用在
+5.7.2 核心原始碼之上，而是套用在基礎 5.7 核心原始碼之上。
+
+因此，要把 5.7.3 修補程式套用到你現有的 5.7.2 核心原始碼，必須先撤銷
+5.7.2 修補程式（回到基礎 5.7 核心原始碼），再套用新的 5.7.3 修補程式。
+
+以下是一個簡單的範例::
+
+ $ cd ~/linux-5.7.2 # change to the kernel source dir
+ $ patch -p1 -R < ../patch-5.7.2 # revert the 5.7.2 patch
+ $ patch -p1 < ../patch-5.7.3 # apply the new 5.7.3 patch
+ $ cd ..
+ $ mv linux-5.7.2 linux-5.7.3 # rename the kernel source dir
+
+增量修補程式
+~~~~~~~~~~~~
+
+增量修補程式則不同：它們不是套用在基礎 5.x 核心之上，而是套用在前一個
+穩定版核心（5.x.y-1）之上。
+
+以下是套用這類修補程式的範例::
+
+ $ cd ~/linux-5.7.2 # change to the kernel source dir
+ $ patch -p1 < ../patch-5.7.2-3 # apply the new 5.7.3 patch
+ $ cd ..
+ $ mv linux-5.7.2 linux-5.7.3 # rename the kernel source dir
+
+
+-rc 核心
+========
+
+這些是候選發布版（release-candidate）核心。每當 Linus 認為目前的 git
+（核心的原始碼管理工具）樹處於相當穩健、足以進行測試的狀態時，就會發布
+這種開發版核心。
+
+這些核心並不穩定，如果你打算執行它們，應該預期偶爾會出問題。不過，這是
+幾個主要開發分支中最穩定的一個，也是最終會成為下一個穩定核心的分支，
+所以讓越多人測試它越好。
+
+如果你想幫忙測試開發版核心，但又不想執行真正實驗性的東西，這是個適合
+執行的分支（想執行實驗性內容的人，請參閱下文關於 -next 與 -mm 核心的
+章節）。
+
+-rc 修補程式不是增量的，它們和上文介紹的 5.x.y 修補程式一樣，套用在
+基礎 5.x 核心之上。-rcN 字尾前面的核心版本，表示這個 -rc 核心最終會
+成為的核心版本。
+
+所以，5.8-rc5 表示這是 5.8 核心的第五個候選發布版，這個修補程式應該
+套用在 5.7 核心原始碼之上。
+
+以下是三個套用這類修補程式的範例::
+
+ # first an example of moving from 5.7 to 5.8-rc3
+
+ $ cd ~/linux-5.7 # change to the 5.7 source dir
+ $ patch -p1 < ../patch-5.8-rc3 # apply the 5.8-rc3 patch
+ $ cd ..
+ $ mv linux-5.7 linux-5.8-rc3 # rename the source dir
+
+ # now let's move from 5.8-rc3 to 5.8-rc5
+
+ $ cd ~/linux-5.8-rc3 # change to the 5.8-rc3 dir
+ $ patch -p1 -R < ../patch-5.8-rc3 # revert the 5.8-rc3 patch
+ $ patch -p1 < ../patch-5.8-rc5 # apply the new 5.8-rc5 patch
+ $ cd ..
+ $ mv linux-5.8-rc3 linux-5.8-rc5 # rename the source dir
+
+ # finally let's try and move from 5.7.3 to 5.8-rc5
+
+ $ cd ~/linux-5.7.3 # change to the kernel source dir
+ $ patch -p1 -R < ../patch-5.7.3 # revert the 5.7.3 patch
+ $ patch -p1 < ../patch-5.8-rc5 # apply new 5.8-rc5 patch
+ $ cd ..
+ $ mv linux-5.7.3 linux-5.8-rc5 # rename the kernel source dir
+
+
+-mm 修補程式與 linux-next 樹
+============================
+
+-mm 修補程式是 Andrew Morton 發布的實驗性修補程式。
+
+過去 -mm 樹也用來測試子系統的修補程式，但這項功能現在改由
+`linux-next` (https://www.kernel.org/doc/man-pages/linux-next.html)
+樹負責。子系統維護者會先把他們的修補程式推送到 linux-next，並在合併視窗
+期間直接發送給 Linus。
+
+-mm 修補程式可以說是新功能和其他未經子系統樹合併的實驗性修補程式的試驗場。
+這類修補程式在 -mm 中經過一段時間證明其價值後，Andrew 就會把它推送給
+Linus，以納入主線。
+
+linux-next 樹每天更新，並包含 -mm 修補程式。兩者都持續變動，包含許多
+實驗性功能、大量不適合進入主線的除錯修補程式等，是本文件所介紹的各分支
+中最具實驗性的。
+
+這些修補程式不適合用在需要保持穩定的系統上，執行它們的風險也比其他任何
+分支都高（請確保你有最新的備份——這適用於任何實驗性核心，對 -mm 修補
+程式或使用 linux-next 樹的核心更是如此）。
+
+我們非常感謝大家測試 -mm 修補程式與 linux-next，因為它們存在的意義，
+就是在變更合併進更穩定的 Linus 主線樹之前，找出迴歸、當機、資料損毀
+缺陷、建置失敗（以及其他一般的缺陷）。
+
+不過，-mm 與 linux-next 的測試者應該要知道，這些樹出問題的頻率比其他
+任何樹都高。
+
+
+各種核心樹的說明到此結束。希望你現在已經清楚如何套用各種修補程式，並能
+幫忙測試核心。
+
+感謝 Randy Dunlap、Rolf Eike Beer、Linus Torvalds、Bodo Eggert、
+Johannes Stezenbach、Grant Coady、Pavel Machek，以及其他可能被我遺漏
+的人，感謝他們對本文件的審閱與貢獻。
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index 80fff2203e55..7917fb96dd01 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -43,13 +43,13 @@
programming-language
coding-style
email-clients
+ applying-patches
volatile-considered-harmful
TODOList:
* changes
* maintainer-pgp-guide
-* applying-patches
* backporting
* adding-syscalls
* botching-up-ioctls
--
2.43.0
^ permalink raw reply [flat|nested] 14+ messages in thread* [PATCH 04/13] docs/zh_TW: process: add maintainer-pgp-guide.rst translation
2026-11-06 11:35 [PATCH 00/13] docs/zh_TW: process: add translations of 13 documents Chen-Yu Yeh
` (2 preceding siblings ...)
2026-11-06 11:35 ` [PATCH 03/13] docs/zh_TW: process: add applying-patches.rst translation Chen-Yu Yeh
@ 2026-11-06 11:35 ` Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 05/13] docs/zh_TW: process: add changes.rst translation Chen-Yu Yeh
` (8 subsequent siblings)
12 siblings, 0 replies; 14+ messages in thread
From: Chen-Yu Yeh @ 2026-11-06 11:35 UTC (permalink / raw)
To: Alex Shi, Jonathan Corbet
Cc: Weijie Yuan, Dongliang Mu, Yanteng Si, linux-doc, linux-kernel,
Chen-Yu Yeh
Translate Documentation/process/maintainer-pgp-guide.rst into
Traditional Chinese from the current English text, including the
GnuPG 2.4 requirement, the Nitrokey 3 entry, the B4 note on patatt and
the updated kernel.org documentation links. The zh_CN translation was
consulted for wording only.
List the new file in the toctree of process/index.rst, after
coding-style as in the English index, and drop it from the TODOList.
update to commit 4a0be1a25d98 ("Documentation: process: Capitalize Git,
Quilt, and Mercurial consistently")
Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
.../translations/zh_TW/process/index.rst | 2 +-
.../zh_TW/process/maintainer-pgp-guide.rst | 795 ++++++++++++++++++
2 files changed, 796 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_TW/process/maintainer-pgp-guide.rst
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index 7917fb96dd01..7b830c48942a 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -42,6 +42,7 @@
programming-language
coding-style
+ maintainer-pgp-guide
email-clients
applying-patches
volatile-considered-harmful
@@ -49,7 +50,6 @@
TODOList:
* changes
-* maintainer-pgp-guide
* backporting
* adding-syscalls
* botching-up-ioctls
diff --git a/Documentation/translations/zh_TW/process/maintainer-pgp-guide.rst b/Documentation/translations/zh_TW/process/maintainer-pgp-guide.rst
new file mode 100644
index 000000000000..34d920cb37cc
--- /dev/null
+++ b/Documentation/translations/zh_TW/process/maintainer-pgp-guide.rst
@@ -0,0 +1,795 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_TW.rst
+
+:Original: Documentation/process/maintainer-pgp-guide.rst
+
+.. _tw_pgpguide:
+
+=======================
+核心維護者 PGP 指南
+=======================
+
+:作者: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
+
+本文件的對象是 Linux 核心開發者，特別是子系統維護者。內容是 Linux 基金會
+發布的、更通用的「`Protecting Code Integrity`_」指南中所討論資訊的一部分。
+若想更深入了解本指南提到的某些主題，請閱讀該文件。
+
+.. _`Protecting Code Integrity`: https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md
+
+PGP 在 Linux 核心開發中的角色
+=============================
+
+PGP 有助於確保 Linux 核心開發社群所產出程式碼的完整性，並在較小程度上，
+透過 PGP 簽名的電子郵件往來，在開發者之間建立可信任的通訊管道。
+
+Linux 核心原始碼主要以兩種形式提供：
+
+- 分散式原始碼儲存庫（Git）
+- 定期發布的快照（tarball）
+
+Git 儲存庫和 tarball 都帶有建立正式核心版本的核心開發者的 PGP 簽名。這些
+簽名提供密碼學上的保證，確保透過 kernel.org 或任何其他鏡像站提供下載的
+版本，與這些開發者工作站上的版本完全相同。為此：
+
+- Git 儲存庫的所有標籤都附有 PGP 簽名
+- tarball 的所有下載檔都附有分離式（detached）PGP 簽名
+
+.. _tw_devs_not_infra:
+
+信任開發者，而非基礎設施
+------------------------
+
+自從 2011 年 kernel.org 核心系統遭到入侵以來，Kernel Archives 專案的主要
+運作原則，就是假設基礎設施的任何部分都可能隨時遭到入侵。因此，管理員刻意
+採取措施，強調信任必須永遠放在開發者身上，而絕不放在程式碼託管基礎設施
+上，不論後者的安全實務做得多好。
+
+上述指導原則正是需要本指南的原因。我們希望確保，把信任放在開發者身上，並
+不只是把未來可能發生的安全事件的責任轉嫁給別人。本指南的目標是提供一套
+準則，讓開發者可以用來建立安全的工作環境，並保護用來確立 Linux 核心本身
+完整性的 PGP 金鑰。
+
+.. _tw_pgp_tools:
+
+PGP 工具
+========
+
+使用 GnuPG 2.4 或更新版本
+-------------------------
+
+你的發行版應該已經預設安裝了 GnuPG，你只需要確認你使用的是夠新的版本。
+要檢查版本，請執行::
+
+ $ gpg --version | head -n1
+
+如果你的版本是 2.4 或以上，那就沒問題了。如果版本更舊，表示你使用的
+GnuPG 版本已經不再維護，本指南中的某些指令可能無法運作。
+
+設定 gpg-agent 選項
+~~~~~~~~~~~~~~~~~~~
+
+GnuPG agent 是一個輔助工具，每當你使用 ``gpg`` 指令時就會自動啟動，並在
+背景執行，用途是快取私鑰的密碼短語。有兩個選項你應該知道，用來調整密碼
+短語何時從快取中失效：
+
+- ``default-cache-ttl`` （秒）：如果你在存活時間（time-to-live）到期前再次
+ 使用同一把金鑰，倒數計時會重設，重新計算一段時間。預設值為 600（10 分
+ 鐘）。
+- ``max-cache-ttl`` （秒）：不論你在第一次輸入密碼短語後最近一次使用金鑰
+ 是什麼時候，只要最長存活時間的倒數計時到期，你就必須再次輸入密碼短語。
+ 預設值為 30 分鐘。
+
+如果你覺得這兩個預設值太短（或太長），可以編輯 ``~/.gnupg/gpg-agent.conf``
+檔案，設定你自己的值::
+
+ # set to 30 minutes for regular ttl, and 2 hours for max ttl
+ default-cache-ttl 1800
+ max-cache-ttl 7200
+
+.. note::
+
+ 現在已經不需要在 shell 工作階段開始時手動啟動 gpg-agent。你可能需要
+ 檢查你的 rc 檔案，移除先前為舊版 GnuPG 所做的設定，因為它們可能已經
+ 不再正確。
+
+.. _tw_protect_your_key:
+
+保護你的 PGP 金鑰
+=================
+
+本指南假設你已經有一把用於 Linux 核心開發的 PGP 金鑰。如果你還沒有，請
+參閱前面提到的「`Protecting Code Integrity`_」文件，了解如何建立新的金鑰。
+
+如果你目前的金鑰強度低於 2048 位元（RSA），你也應該建立一把新的金鑰。
+
+了解 PGP 子金鑰
+---------------
+
+PGP 金鑰很少只由單一金鑰對組成——通常它是一組彼此獨立的子金鑰，可依其
+建立時所指派的能力用於不同用途。PGP 定義了金鑰可以具備的四種能力：
+
+- **[S]** 金鑰可用於簽名
+- **[E]** 金鑰可用於加密
+- **[A]** 金鑰可用於身分驗證
+- **[C]** 金鑰可用於認證其他金鑰
+
+具備 **[C]** 能力的金鑰常被稱為「主」金鑰（master key），但這個說法容易
+造成誤解，因為它暗示認證金鑰可以取代同一條鏈上的任何其他子金鑰（就像實體
+的「萬能鑰匙」可以打開為其他鑰匙打造的鎖）。由於事實並非如此，本指南將它
+稱為「認證金鑰」（Certify key），以避免任何歧義。
+
+務必完全理解以下幾點：
+
+1. 所有子金鑰彼此完全獨立。如果你遺失了某把私有子金鑰，就無法從你鏈上的
+ 任何其他私鑰還原或重新產生它。
+2. 除了認證金鑰之外，可以有多把能力相同的子金鑰（例如，你可以有 2 把有效
+ 的加密子金鑰、3 把有效的簽名子金鑰，但只能有一把有效的認證子金鑰）。
+ 所有子金鑰都完全獨立——加密給某一把 **[E]** 子金鑰的訊息，無法用你
+ 可能擁有的任何其他 **[E]** 子金鑰解密。
+3. 單一子金鑰可以具備多種能力（例如，你的 **[C]** 金鑰也可以同時是你的
+ **[S]** 金鑰）。
+
+具備 **[C]** （認證）能力的金鑰，是唯一可以用來表示與其他金鑰之間關係的
+金鑰。只有 **[C]** 金鑰可以用來：
+
+- 新增或撤銷具備 S/E/A 能力的其他金鑰（子金鑰）
+- 新增、變更或撤銷與該金鑰關聯的身分（uid）
+- 新增或變更它自己或任何子金鑰的到期日
+- 為了信任網的目的簽署其他人的金鑰
+
+GnuPG 在產生新金鑰時，預設會建立以下內容：
+
+- 一把同時具備認證與簽名能力的子金鑰（**[SC]**）
+- 一把具備加密能力的獨立子金鑰（**[E]**）
+
+如果你產生金鑰時使用的是預設參數，那麼你擁有的就是這些。你可以執行
+``gpg --list-secret-keys`` 來確認，例如::
+
+ sec ed25519 2022-12-20 [SC] [expires: 2024-12-19]
+ 000000000000000000000000AAAABBBBCCCCDDDD
+ uid [ultimate] Alice Dev <adev@kernel.org>
+ ssb cv25519 2022-12-20 [E] [expires: 2024-12-19]
+
+``sec`` 項目下方那一長串就是你的金鑰指紋——在下面的範例中，每當你看到
+``[fpr]``，指的就是這個 40 個字元的字串。
+
+確保你的密碼短語夠強
+--------------------
+
+GnuPG 會先用密碼短語加密你的私鑰，再把它們儲存到磁碟上。如此一來，即使
+你的整個 ``.gnupg`` 目錄外洩或被竊，攻擊者若沒有先取得用來解密的密碼
+短語，也無法使用你的私鑰。
+
+用強度足夠的密碼短語保護你的私鑰是絕對必要的。要設定或變更密碼短語，請
+使用::
+
+ $ gpg --change-passphrase [fpr]
+
+建立獨立的簽名子金鑰
+--------------------
+
+我們的目標是把你的認證金鑰移到離線媒體上加以保護，所以如果你只有一把合併
+的 **[SC]** 金鑰，就應該另外建立一把獨立的簽名子金鑰::
+
+ $ gpg --quick-addkey [fpr] ed25519 sign
+
+備份你的認證金鑰以供災難復原
+----------------------------
+
+你的 PGP 金鑰上來自其他開發者的簽名越多，你就越有理由為了災難復原，建立
+一份存放在數位媒體以外的備份。
+
+要製作私鑰的可列印紙本，一個好方法是使用專為此目的撰寫的 ``paperkey``
+軟體。關於其輸出格式，以及它相較於其他方案的優點，請參閱
+``man paperkey``。大多數發行版應該都已經有 Paperkey 的套件。
+
+執行以下指令，建立私鑰的紙本備份::
+
+ $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt
+
+把該檔案列印出來，然後拿一支筆，把你的密碼短語寫在紙張的邊緣。**強烈建議
+這麼做**，因為印出來的金鑰仍然是用該密碼短語加密的，而如果你哪天變更了
+密碼短語，你將不會記得建立備份時用的是哪一個——*保證如此*。
+
+把印好的紙本和手寫的密碼短語放進信封，存放在安全且受到妥善保護的地方，
+最好不在你家裡，例如銀行的保險箱。
+
+.. note::
+
+ 金鑰仍然是用你的密碼短語加密的，所以即使用「整合雲端」的現代印表機
+ 列印，也應該仍是相對安全的操作。
+
+備份你的整個 GnuPG 目錄
+-----------------------
+
+.. warning::
+
+ **!!!不要跳過這個步驟!!!**
+
+當你需要復原 PGP 金鑰時，手邊有一份隨時可用的備份是很重要的。這和我們用
+``paperkey`` 所做的災難等級準備不同。每當你需要使用認證金鑰時——例如變更
+你自己的金鑰，或在研討會和高峰會之後簽署其他人的金鑰——你也會依賴這些
+外部副本。
+
+首先，準備一張外接儲存卡（最好是兩張！）作為備份用途。你需要用 LUKS 在
+這個裝置上建立一個加密分割區——如何操作請參閱你的發行版文件。
+
+加密用的密碼短語可以和你的 PGP 金鑰使用同一個。
+
+加密程序完成後，重新插入你的裝置，並確認它已正確掛載。把你的整個
+``.gnupg`` 目錄複製到加密儲存裝置上::
+
+ $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup
+
+現在你應該測試一下，確認一切仍然正常運作::
+
+ $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr]
+
+如果沒有出現任何錯誤，那就沒問題了。卸載裝置，清楚地標示它，以免不小心
+覆寫，然後把它放在安全的地方——但不要放得太遠，因為你偶爾還需要用它來
+做一些事，例如編輯身分、新增或撤銷子金鑰，或簽署其他人的金鑰。
+
+從主目錄中移除認證金鑰
+----------------------
+
+我們主目錄中的檔案，並沒有我們想像中受到那麼好的保護。它們可能透過許多
+不同的途徑外洩或被竊：
+
+- 為了設定新工作站而快速複製主目錄時意外外洩
+- 系統管理員的疏忽或惡意
+- 保護不周的備份
+- 桌面應用程式（瀏覽器、pdf 檢視器等）中的惡意軟體
+- 跨越國境時遭到脅迫
+
+用好的密碼短語保護金鑰，可以大幅降低上述任何一種風險，但密碼短語仍可能
+透過鍵盤側錄程式、偷窺螢幕或其他各種方式被發現。因此，建議的做法是把
+認證金鑰從主目錄中移除，存放在離線儲存裝置上。
+
+.. warning::
+
+ 請參閱上一節，確認你已經完整備份了 GnuPG 目錄。如果你沒有可用的
+ 備份，我們接下來要做的事會讓你的金鑰變得無法使用！
+
+首先，找出你的認證金鑰的「keygrip」::
+
+ $ gpg --with-keygrip --list-key [fpr]
+
+輸出會類似這樣::
+
+ pub ed25519 2022-12-20 [SC] [expires: 2022-12-19]
+ 000000000000000000000000AAAABBBBCCCCDDDD
+ Keygrip = 1111000000000000000000000000000000000000
+ uid [ultimate] Alice Dev <adev@kernel.org>
+ sub cv25519 2022-12-20 [E] [expires: 2022-12-19]
+ Keygrip = 2222000000000000000000000000000000000000
+ sub ed25519 2022-12-20 [S]
+ Keygrip = 3333000000000000000000000000000000000000
+
+找出位於 ``pub`` 那一行下方（就在認證金鑰指紋的正下方）的 keygrip 項目。
+它會直接對應到你 ``~/.gnupg`` 目錄中的一個檔案::
+
+ $ cd ~/.gnupg/private-keys-v1.d
+ $ ls
+ 1111000000000000000000000000000000000000.key
+ 2222000000000000000000000000000000000000.key
+ 3333000000000000000000000000000000000000.key
+
+只要移除與認證金鑰 keygrip 對應的 .key 檔案就夠了::
+
+ $ cd ~/.gnupg/private-keys-v1.d
+ $ rm 1111000000000000000000000000000000000000.key
+
+現在如果你執行 ``--list-secret-keys`` 指令，它會顯示認證金鑰已經不在
+（``#`` 表示該金鑰無法使用）::
+
+ $ gpg --list-secret-keys
+ sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19]
+ 000000000000000000000000AAAABBBBCCCCDDDD
+ uid [ultimate] Alice Dev <adev@kernel.org>
+ ssb cv25519 2022-12-20 [E] [expires: 2024-12-19]
+ ssb ed25519 2022-12-20 [S]
+
+你也應該移除 ``~/.gnupg`` 目錄中所有的 ``secring.gpg`` 檔案，它們可能是
+舊版 GnuPG 留下來的。
+
+如果你沒有「private-keys-v1.d」目錄
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+如果你沒有 ``~/.gnupg/private-keys-v1.d`` 目錄，表示你的密鑰仍然儲存在
+GnuPG v1 所使用的舊式 ``secring.gpg`` 檔案中。對金鑰做任何變更，例如變更
+密碼短語或新增子金鑰，應該都會自動把舊的 ``secring.gpg`` 格式轉換為使用
+``private-keys-v1.d``。
+
+完成之後，務必刪除已過時的 ``secring.gpg`` 檔案，因為它仍然含有你的
+私鑰。
+
+.. _tw_smartcards:
+
+將子金鑰移到專用的加密裝置
+==========================
+
+雖然認證金鑰現在已經不會外洩或被竊，但子金鑰仍然在你的主目錄中。任何
+設法取得這些子金鑰的人，都能夠解密你的通訊或偽造你的簽名（如果他們知道
+密碼短語）。此外，每次執行 GnuPG 操作時，金鑰都會被載入系統記憶體，夠
+先進的惡意軟體可以從那裡把它們偷走（想想 Meltdown 和 Spectre）。
+
+要完整保護你的金鑰，一個好方法是把它們移到能夠執行智慧卡操作的專用硬體
+裝置上。
+
+智慧卡的好處
+------------
+
+智慧卡內含一顆加密晶片，能夠儲存私鑰，並直接在卡片上執行加密運算。由於
+金鑰內容永遠不會離開智慧卡，插入該硬體裝置的電腦，其作業系統無法取得私鑰
+本身。這和我們先前用於備份的加密儲存裝置大不相同——那個裝置在插入並掛載
+時，作業系統是能夠存取私鑰內容的。
+
+使用外接加密媒體並不能取代具備智慧卡功能的裝置。
+
+可用的智慧卡裝置
+----------------
+
+除非你所有的筆記型電腦和工作站都有智慧卡讀卡機，否則最簡單的做法是取得
+一個實作智慧卡功能的專用 USB 裝置。有幾種選擇：
+
+- `Nitrokey Start`_：開放硬體與自由軟體，以 FSI Japan 的 `Gnuk`_ 為
+ 基礎。最便宜的選擇之一，但提供的安全功能最少（例如防竄改或抵抗某些
+ 旁通道攻擊）。
+- `Nitrokey 3`_：與 Nitrokey Start 類似，但更能防竄改，並提供更多安全
+ 功能和 USB 外形規格。支援 ECC 密碼學（ED25519 和 NISTP）。
+- `Yubikey 5`_：專有的硬體與軟體，但比 Nitrokey 便宜，功能也相近。支援
+ ECC 密碼學（ED25519 和 NISTP）。
+
+你的選擇將取決於成本、在你所在地區能否運送，以及對開放或專有硬體的考量。
+
+.. note::
+
+ 如果你列在 MAINTAINERS 的 `M:` 項目中，或擁有 kernel.org 帳號，你就
+ `qualify for a free Nitrokey Start`_ （有資格免費獲得 Linux 基金會
+ 提供的 Nitrokey Start）。
+
+.. _`Nitrokey Start`: https://www.nitrokey.com/products/nitrokeys
+.. _`Nitrokey 3`: https://www.nitrokey.com/products/nitrokeys
+.. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/
+.. _Gnuk: https://www.fsij.org/doc-gnuk/
+.. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html
+
+設定你的智慧卡裝置
+------------------
+
+你的智慧卡裝置一插上任何現代的 Linux 工作站，就應該能直接運作（Just Work
+(TM)）。你可以執行以下指令確認::
+
+ $ gpg --card-status
+
+如果你看到完整的智慧卡詳細資訊，那就沒問題了。可惜的是，要排除所有可能
+導致無法運作的原因，遠遠超出本指南的範圍。如果你無法讓智慧卡與 GnuPG
+搭配運作，請透過一般的支援管道尋求協助。
+
+要設定你的智慧卡，你需要使用 GnuPG 的選單系統，因為沒有方便的命令列
+選項::
+
+ $ gpg --card-edit
+ [...omitted...]
+ gpg/card> admin
+ Admin commands are allowed
+ gpg/card> passwd
+
+你應該設定使用者 PIN（1）、管理員 PIN（3）和重設碼（4）。請務必把這些
+記錄下來並存放在安全的地方——特別是管理員 PIN 和重設碼（重設碼可以讓你
+完全清除智慧卡）。你很少需要用到管理員 PIN，所以如果不記錄下來，你一定會
+忘記它是什麼。
+
+回到卡片主選單後，你也可以設定其他值（例如姓名、性別、登入資料等），但這
+並非必要，而且萬一你遺失了智慧卡，還會額外洩漏關於這張智慧卡的資訊。
+
+.. note::
+
+ 雖然名稱叫做「PIN」，但卡片上的使用者 PIN 和管理員 PIN 都不一定要是
+ 數字。
+
+.. warning::
+
+ 某些裝置可能要求你先把子金鑰移到裝置上，才能變更密碼短語。請查閱
+ 裝置製造商提供的文件。
+
+將子金鑰移到你的智慧卡
+----------------------
+
+離開卡片選單（使用「q」）並儲存所有變更。接下來，我們把你的子金鑰移到
+智慧卡上。大多數操作都會同時需要你的 PGP 金鑰密碼短語和卡片的管理員
+PIN::
+
+ $ gpg --edit-key [fpr]
+
+ Secret subkeys are available.
+
+ pub ed25519/AAAABBBBCCCCDDDD
+ created: 2022-12-20 expires: 2024-12-19 usage: SC
+ trust: ultimate validity: ultimate
+ ssb cv25519/1111222233334444
+ created: 2022-12-20 expires: never usage: E
+ ssb ed25519/5555666677778888
+ created: 2017-12-07 expires: never usage: S
+ [ultimate] (1). Alice Dev <adev@kernel.org>
+
+ gpg>
+
+使用 ``--edit-key`` 會讓我們再次進入選單模式，你會注意到金鑰列表有點
+不同。從這裡開始，所有指令都在這個選單模式中執行，如 ``gpg>`` 所示。
+
+首先，選擇我們要放到卡片上的金鑰——方法是輸入 ``key 1`` （它是列表中的
+第一把，也就是 **[E]** 子金鑰）::
+
+ gpg> key 1
+
+現在你應該會在輸出中看到 **[E]** 金鑰變成 ``ssb*``。``*`` 表示目前「被
+選取」的是哪一把金鑰。它的作用是 *切換*，也就是說，如果你再輸入一次
+``key 1``，``*`` 就會消失，該金鑰也就不再被選取。
+
+現在，把那把金鑰移到智慧卡上::
+
+ gpg> keytocard
+ Please select where to store the key:
+ (2) Encryption key
+ Your selection? 2
+
+由於這是我們的 **[E]** 金鑰，把它放進加密（Encryption）槽位是合理的。
+送出選擇後，系統會先要求你輸入 PGP 金鑰的密碼短語，然後再要求輸入管理員
+PIN。如果指令執行完畢且沒有出現錯誤，你的金鑰就已經移過去了。
+
+**重要**：現在再輸入一次 ``key 1`` 取消選取第一把金鑰，然後輸入
+``key 2`` 選取 **[S]** 金鑰::
+
+ gpg> key 1
+ gpg> key 2
+ gpg> keytocard
+ Please select where to store the key:
+ (1) Signature key
+ (3) Authentication key
+ Your selection? 1
+
+**[S]** 金鑰可以同時用於簽名（Signature）和身分驗證（Authentication），
+但我們希望確保它放在簽名槽位中，所以選擇（1）。同樣地，如果指令執行完畢
+且沒有出現錯誤，操作就成功了::
+
+ gpg> q
+ Save changes? (y/N) y
+
+儲存變更後，你移到卡片上的那些金鑰會從主目錄中刪除（不過沒關係，因為我們
+的備份裡還有，如果之後要為替換的智慧卡再做一次，就可以使用）。
+
+確認金鑰已經移過去
+~~~~~~~~~~~~~~~~~~
+
+如果你現在執行 ``--list-secret-keys``，會在輸出中看到細微的差異::
+
+ $ gpg --list-secret-keys
+ sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19]
+ 000000000000000000000000AAAABBBBCCCCDDDD
+ uid [ultimate] Alice Dev <adev@kernel.org>
+ ssb> cv25519 2022-12-20 [E] [expires: 2024-12-19]
+ ssb> ed25519 2022-12-20 [S]
+
+``ssb>`` 中的 ``>`` 表示該子金鑰只存在於智慧卡上。如果你回到密鑰目錄檢視
+裡面的內容，會發現那裡的 ``.key`` 檔案都已經被替換成存根（stub）::
+
+ $ cd ~/.gnupg/private-keys-v1.d
+ $ strings *.key | grep 'private-key'
+
+輸出中應該會有 ``shadowed-private-key``，表示這些檔案只是存根，實際的
+內容在智慧卡上。
+
+確認智慧卡正常運作
+~~~~~~~~~~~~~~~~~~
+
+要確認智慧卡如預期運作，你可以建立一個簽名::
+
+ $ echo "Hello world" | gpg --clearsign > /tmp/test.asc
+ $ gpg --verify /tmp/test.asc
+
+執行第一個指令時，應該會要求你輸入智慧卡 PIN，接著在你執行
+``gpg --verify`` 後顯示「Good signature」。
+
+恭喜，你已經成功讓別人極難竊取你的數位開發者身分！
+
+其他常見的 GnuPG 操作
+---------------------
+
+以下是一些你會需要對 PGP 金鑰執行的常見操作的快速參考。
+
+掛載你的安全離線儲存裝置
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+以下任何一項操作都需要用到認證金鑰，所以你首先需要掛載你的離線備份儲存
+裝置，並告訴 GnuPG 使用它::
+
+ $ export GNUPGHOME=/media/disk/foo/gnupg-backup
+ $ gpg --list-secret-keys
+
+你要確認輸出中顯示的是 ``sec`` 而不是 ``sec#`` （``#`` 表示該金鑰無法
+使用，而你仍在使用一般的主目錄位置）。
+
+延長金鑰的到期日
+~~~~~~~~~~~~~~~~
+
+認證金鑰的預設到期日是建立日起 2 年。這麼做既是出於安全考量，也是為了讓
+過時的金鑰最終從金鑰伺服器上消失。
+
+要把金鑰的到期日從今天起延長一年，只要執行::
+
+ $ gpg --quick-set-expire [fpr] 1y
+
+如果使用特定日期比較好記，你也可以這麼做（例如你的生日、1 月 1 日或
+加拿大國慶日）::
+
+ $ gpg --quick-set-expire [fpr] 2038-07-01
+
+記得把更新後的金鑰發送回金鑰伺服器::
+
+ $ gpg --send-key [fpr]
+
+做了任何變更之後更新你的工作目錄
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+當你使用離線儲存裝置對金鑰做了任何變更之後，會需要把這些變更匯入回你平常
+的工作目錄::
+
+ $ gpg --export | gpg --homedir ~/.gnupg --import
+ $ unset GNUPGHOME
+
+透過 ssh 使用 gpg-agent
+~~~~~~~~~~~~~~~~~~~~~~~
+
+如果你需要在遠端系統上簽署標籤或提交，可以透過 ssh 轉送你的 gpg-agent。
+請參考 GnuPG wiki 上提供的說明：
+
+- `Agent Forwarding over SSH`_
+
+如果你能修改遠端的 sshd 伺服器設定，運作起來會更順暢。
+
+.. _`Agent Forwarding over SSH`: https://wiki.gnupg.org/AgentForwarding
+
+.. _tw_pgp_with_git:
+
+在 Git 中使用 PGP
+=================
+
+Git 的核心特色之一是它的分散式本質——一旦把儲存庫複製到你的系統上，你就
+擁有該專案的完整歷史，包括它所有的標籤、提交和分支。然而，當外面流傳著
+數以百計的複製儲存庫時，任何人要如何確認自己手上的 linux.git 副本沒有
+被惡意第三方竄改？
+
+又或者，如果在核心中發現了惡意程式碼，而提交中的「Author」行說是你做的，
+但你很確定自己 `跟它毫無關係`_，那又會怎樣？
+
+為了同時解決這兩個問題，Git 引入了 PGP 整合。簽名標籤可以確保儲存庫的
+內容與建立該標籤的開發者工作站上的內容完全相同，藉此證明儲存庫的完整性；
+而簽名提交則讓別人在無法取得你的 PGP 金鑰的情況下，幾乎不可能冒充你。
+
+.. _`跟它毫無關係`: https://github.com/jayphelps/git-blame-someone-else
+
+設定 Git 使用你的 PGP 金鑰
+--------------------------
+
+如果你的金鑰環中只有一把密鑰，那其實不需要做任何額外的事，因為它就會是你
+的預設金鑰。不過，如果你剛好有多把密鑰，可以告訴 Git 應該使用哪一把
+（``[fpr]`` 是你金鑰的指紋）::
+
+ $ git config --global user.signingKey [fpr]
+
+如何使用簽名標籤
+----------------
+
+要建立簽名標籤，請在 tag 指令加上 ``-s`` 選項::
+
+ $ git tag -s [tagname]
+
+我們建議一律簽署 Git 標籤，因為這能讓其他開發者確認他們拉取的 Git 儲存庫
+沒有遭到惡意竄改。
+
+如何驗證簽名標籤
+~~~~~~~~~~~~~~~~
+
+要驗證簽名標籤，請使用 ``verify-tag`` 指令::
+
+ $ git verify-tag [tagname]
+
+如果你是從專案儲存庫的另一個分叉拉取標籤，Git 應該會自動驗證你所拉取的
+最新端點上的簽名，並在合併操作期間顯示結果::
+
+ $ git pull [url] tags/sometag
+
+合併訊息中會包含類似以下的內容::
+
+ Merge tag 'sometag' of [url]
+
+ [Tag message]
+
+ # gpg: Signature made [...]
+ # gpg: Good signature from [...]
+
+如果你要驗證別人的 Git 標籤，首先需要匯入他們的 PGP 金鑰。請參閱下面的
+「:ref:`tw_verify_identities`」一節。
+
+設定 Git 一律簽署附註標籤
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+如果你要建立附註標籤（annotated tag），你很可能也會想要簽署它。要強制
+Git 一律簽署附註標籤，可以設定一個全域設定選項::
+
+ $ git config --global tag.forceSignAnnotated true
+
+如何使用簽名提交
+----------------
+
+你也可以建立簽名提交，但它們在 Linux 核心開發中的用處有限。核心的貢獻
+流程仰賴寄送修補程式，而把提交轉換成修補程式並不會保留 Git 提交簽名。
+此外，把你自己的儲存庫 rebase 到較新的上游版本時，PGP 提交簽名最後也會
+被捨棄。因此，大多數核心開發者並不費心簽署自己的提交，也會忽略他們工作
+所依賴的任何外部儲存庫中的簽名提交。
+
+話雖如此，如果你的工作用 Git 樹公開放在某個 Git 託管服務上（kernel.org、
+infradead.org、ozlabs.org 或其他），那麼即使上游開發者無法直接從這種做法
+中受益，我們仍建議你簽署所有的 Git 提交。
+
+我們建議這麼做的理由如下：
+
+1. 如果有一天需要進行程式碼鑑識或追查程式碼來源，即使是在外部維護、帶有
+ PGP 提交簽名的樹，對這類用途也很有價值。
+2. 如果你需要重新複製本地儲存庫（例如，重新安裝系統之後），這可以讓你在
+ 繼續工作之前驗證儲存庫的完整性。
+3. 如果有人需要 cherry-pick 你的提交，這能讓他們在套用之前快速驗證這些
+ 提交的完整性。
+
+建立簽名提交
+~~~~~~~~~~~~
+
+要建立簽名提交，請在 ``git commit`` 指令加上 ``-S`` 旗標（因為和另一個
+旗標衝突，所以是大寫的 ``-S``）::
+
+ $ git commit -S
+
+設定 Git 一律簽署提交
+~~~~~~~~~~~~~~~~~~~~~
+
+你可以告訴 Git 一律簽署提交::
+
+ git config --global commit.gpgSign true
+
+.. note::
+
+ 在開啟這個選項之前，請務必先設定好 ``gpg-agent``。
+
+.. _tw_verify_identities:
+
+如何使用簽名修補程式
+--------------------
+
+你可以用 PGP 金鑰簽署發送到核心開發者郵件列表的修補程式。由於現有的電子
+郵件簽名機制（PGP-Mime 或 PGP-inline）往往會對一般的程式碼審查工作造成
+問題，你應該使用 kernel.org 為此目的建立的工具，它會把密碼學證明
+（attestation）簽名放進郵件標頭中（類似 DKIM）：
+
+- `Patatt Patch Attestation`_
+
+.. _`Patatt Patch Attestation`: https://pypi.org/project/patatt/
+
+安裝與設定 patatt
+~~~~~~~~~~~~~~~~~
+
+.. note::
+
+ 如果你使用 B4 寄送修補程式，patatt 已經安裝好並整合進你的工作流程中。
+
+許多發行版都已經有 Patatt 的套件，所以請先到那裡找找看。你也可以用
+「``pip install patatt``」從 pypi 安裝。
+
+如果你已經在 Git 中設定好 PGP 金鑰（透過 ``user.signingKey`` 設定參數），
+那麼 patatt 不需要任何額外設定。你可以在想要的儲存庫中安裝 git-send-email
+掛鉤（hook），開始簽署你的修補程式::
+
+ patatt install-hook
+
+現在，你用 ``git send-email`` 發送的任何修補程式，都會自動加上你的密碼學
+簽名。
+
+檢查 patatt 簽名
+~~~~~~~~~~~~~~~~
+
+如果你使用 ``b4`` 取得並套用修補程式，它會自動嘗試驗證遇到的所有 DKIM 和
+patatt 簽名，例如::
+
+ $ b4 am 20220720205013.890942-1-broonie@kernel.org
+ [...]
+ Checking attestation on all messages, may take a moment...
+ ---
+ ✓ [PATCH v1 1/3] kselftest/arm64: Correct buffer allocation for SVE Z registers
+ ✓ [PATCH v1 2/3] arm64/sve: Document our actual ABI for clearing registers on syscall
+ ✓ [PATCH v1 3/3] kselftest/arm64: Enforce actual ABI for SVE syscalls
+ ---
+ ✓ Signed: openpgp/broonie@kernel.org
+ ✓ Signed: DKIM/kernel.org
+
+.. note::
+
+ Patatt 和 b4 仍在積極開發中，你應該查閱這些專案的最新文件，了解任何
+ 新增或更新的功能。
+
+.. _tw_kernel_identities:
+
+如何驗證核心開發者的身分
+========================
+
+簽署標籤和提交很簡單，但要如何確認用來簽署某樣東西的金鑰，確實屬於那位
+核心開發者，而不是屬於惡意的冒名者？
+
+使用 WKD 和 DANE 設定自動擷取金鑰
+---------------------------------
+
+如果你還沒有大量收集其他開發者的公鑰，可以靠金鑰的自動探索與自動擷取來
+快速建立你的金鑰環。如果從零開始建立你自己的信任網（Web of Trust）讓你
+望而卻步，GnuPG 可以借助其他委派信任技術，也就是 DNSSEC 和 TLS，讓你
+先開始使用。
+
+把以下內容加到你的 ``~/.gnupg/gpg.conf``::
+
+ auto-key-locate wkd,dane,local
+ auto-key-retrieve
+
+基於 DNS 的具名實體認證（DNS-Based Authentication of Named Entities，
+「DANE」）是一種在 DNS 中發布公鑰，並使用 DNSSEC 簽名區域來保護它們的
+方法。Web 金鑰目錄（Web Key Directory，「WKD」）則是另一種方法，使用
+https 查詢來達到同樣的目的。使用 DANE 或 WKD 查詢公鑰時，GnuPG 會分別先
+驗證 DNSSEC 或 TLS 憑證，才把自動擷取到的公鑰加入你的本地金鑰環。
+
+Kernel.org 為所有擁有 kernel.org 帳號的開發者發布 WKD。在你的
+``gpg.conf`` 做了上述變更之後，就可以自動擷取 Linus Torvalds 和
+Greg Kroah-Hartman 的金鑰（如果你還沒有的話）::
+
+ $ gpg --locate-keys torvalds@kernel.org gregkh@kernel.org
+
+如果你有 kernel.org 帳號，那麼你應該 `把 kernel.org UID 加到你的金鑰`_，
+讓 WKD 對其他核心開發者更有用。
+
+.. _`把 kernel.org UID 加到你的金鑰`: https://korg.docs.kernel.org/mail.html#adding-a-kernel-org-uid-to-your-pgp-key
+
+信任網（WOT）與首次使用信任（TOFU）
+-----------------------------------
+
+PGP 包含一種稱為「信任網」（Web of Trust）的信任委派機制。其核心是試圖
+取代 HTTPS/TLS 世界中對集中式憑證授權單位（Certification Authority）的
+需求。PGP 不讓各家軟體廠商來決定誰應該是你信任的認證實體，而是把這個責任
+交給每一位使用者。
+
+可惜的是，很少有人了解信任網是如何運作的。雖然它仍是 OpenPGP 規範中重要
+的一部分，但較新版本的 GnuPG（2.2 及以上）已經實作了另一種稱為「首次使用
+信任」（Trust on First Use，TOFU）的機制。你可以把 TOFU 想成「類似 SSH 的
+信任方式」。使用 SSH 時，第一次連線到遠端系統，其金鑰指紋就會被記錄並
+記住。如果之後金鑰改變了，SSH 用戶端會警告你並拒絕連線，迫使你決定是否
+要信任改變後的金鑰。同樣地，第一次匯入某人的 PGP 金鑰時，它會被假定為
+有效。如果之後 GnuPG 在任何時候遇到另一把身分相同的金鑰，先前匯入的金鑰
+和新金鑰都會被標記為需要驗證，你必須手動判斷要保留哪一把。
+
+我們建議你使用合併的 TOFU+PGP 信任模型（這是 GnuPG v2 新的預設值）。要
+設定它，請在 ``~/.gnupg/gpg.conf`` 中新增（或修改）``trust-model``
+設定::
+
+ trust-model tofu+pgp
+
+.. _tw_kernel_org_trust_repository:
+
+使用 kernel.org 信任網儲存庫
+----------------------------
+
+Kernel.org 維護一個存放開發者公鑰的 Git 儲存庫，用來取代過去幾年大多已經
+停擺的同步式金鑰伺服器網路。關於如何把該儲存庫設定為你的公鑰來源，完整
+文件可以在這裡找到：
+
+- `Kernel developer PGP Keyring`_
+
+如果你是核心開發者，請考慮提交你的金鑰，讓它收錄到該金鑰環中。
+
+.. _`Kernel developer PGP Keyring`: https://korg.docs.kernel.org/pgpkeys.html
--
2.43.0
^ permalink raw reply [flat|nested] 14+ messages in thread* [PATCH 05/13] docs/zh_TW: process: add changes.rst translation
2026-11-06 11:35 [PATCH 00/13] docs/zh_TW: process: add translations of 13 documents Chen-Yu Yeh
` (3 preceding siblings ...)
2026-11-06 11:35 ` [PATCH 04/13] docs/zh_TW: process: add maintainer-pgp-guide.rst translation Chen-Yu Yeh
@ 2026-11-06 11:35 ` Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 06/13] docs/zh_TW: process: add handling-regressions.rst translation Chen-Yu Yeh
` (7 subsequent siblings)
12 siblings, 0 replies; 14+ messages in thread
From: Chen-Yu Yeh @ 2026-11-06 11:35 UTC (permalink / raw)
To: Alex Shi, Jonathan Corbet
Cc: Weijie Yuan, Dongliang Mu, Yanteng Si, linux-doc, linux-kernel,
Chen-Yu Yeh
Translate Documentation/process/changes.rst into Traditional Chinese
from the current English text, including the minimum version table
(Clang/LLVM 17.0.1, Rust 1.85.0, bindgen 0.71.1, pahole 1.26) and the
GNU AWK, mkimage and rustdoc sections. There is no zh_CN translation
of this file to consult.
List the new file in the toctree of process/index.rst, before
programming-language as in the English index, and drop it from the
TODOList.
update to commit fd5425b67355 ("docs, resolve_btfids: Document kfunc
BTF annotation emission")
Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
.../translations/zh_TW/process/changes.rst | 532 ++++++++++++++++++
.../translations/zh_TW/process/index.rst | 2 +-
2 files changed, 533 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_TW/process/changes.rst
diff --git a/Documentation/translations/zh_TW/process/changes.rst b/Documentation/translations/zh_TW/process/changes.rst
new file mode 100644
index 000000000000..1d30b22b7d31
--- /dev/null
+++ b/Documentation/translations/zh_TW/process/changes.rst
@@ -0,0 +1,532 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_TW.rst
+
+:Original: Documentation/process/changes.rst
+
+.. _tw_changes:
+
+編譯核心的最低需求
+++++++++++++++++++
+
+簡介
+====
+
+本文件列出執行目前版本核心所需的最低軟體版本。
+
+本文件最初是以我為 2.0.x 核心所寫的「Changes」檔案為基礎，因此要感謝的人
+也和那份檔案相同（Jared Mauch、Axel Boldt、Alessandro Sigala，以及網路上
+無數的其他使用者）。
+
+目前的最低需求
+**************
+
+在認為自己遇到缺陷之前，請 **至少** 先升級到下列軟體版本！如果不確定目前
+執行的是哪個版本，表中建議的指令應該可以告訴你。如果要列出系統上這些程式
+的版本，請執行 ./scripts/ver_linux
+
+再次提醒，這份清單假設你已經能夠正常執行 Linux 核心。此外，並不是每個系統
+都需要所有工具；舉例來說，如果你沒有任何 PC Card 硬體，大概就不必理會
+pcmciautils。
+
+====================== =============== ========================================
+程式 最低版本 檢查版本的指令
+====================== =============== ========================================
+bash 4.2 bash --version
+bc 1.06.95 bc --version
+bindgen（選用） 0.71.1 bindgen --version
+binutils 2.30 ld -v
+bison 2.0 bison --version
+btrfs-progs 0.18 btrfs --version
+Clang/LLVM（選用） 17.0.1 clang --version
+e2fsprogs 1.41.4 e2fsck -V
+flex 2.5.35 flex --version
+gdb 7.2 gdb --version
+GNU awk（選用） 5.1.0 gawk --version
+GNU C 8.1 gcc --version
+GNU make 4.0 make --version
+GNU tar 1.28 tar --version
+GRUB 0.93 grub --version || grub-install --version
+gtags（選用） 6.6.5 gtags --version
+iptables 1.4.2 iptables -V
+jfsutils 1.1.3 fsck.jfs -V
+kmod 13 kmod -V
+mcelog 0.6 mcelog --version
+mkimage（選用） 2017.01 mkimage --version
+nfs-utils 1.0.5 showmount --version
+openssl & libcrypto 1.0.0 openssl version
+pahole 1.26 pahole --version
+pcmciautils 004 pccardctl -V
+PPP 2.4.0 pppd --version
+procps 3.2.0 ps --version
+Python 3.9.x python3 --version
+quota-tools 3.09 quota -V
+Rust（選用） 1.85.0 rustc --version
+Sphinx\ [#f1]_ 3.4.3 sphinx-build --version
+squashfs-tools 4.0 mksquashfs -version
+udev 081 udevadm --version
+util-linux 2.10o mount --version
+xfsprogs 2.6.0 xfs_db -V
+====================== =============== ========================================
+
+.. [#f1] 只有建置核心文件時才需要 Sphinx
+
+核心編譯
+********
+
+GCC
+---
+
+gcc 的版本需求可能會因電腦的 CPU 類型而有所不同。
+
+Clang/LLVM（選用）
+------------------
+
+建置核心時支援 clang 與 LLVM 工具的最新正式版本（依據
+`releases.llvm.org <https://releases.llvm.org>`_）。不保證舊版本可以正常
+運作，而且我們可能會從核心中移除過去為了支援舊版本而加入的權宜措施。更多
+說明請參閱 :ref:`使用 Clang/LLVM 建置 Linux <kbuild_llvm>`。
+
+Rust（選用）
+------------
+
+需要較新版本的 Rust 編譯器。
+
+如何滿足 Rust 支援的建置需求，請參閱 Documentation/rust/quick-start.rst。
+特別是 ``Makefile`` 的 ``rustavailable`` 目標，可以用來檢查為什麼偵測不到
+Rust 工具鏈。
+
+bindgen（選用）
+---------------
+
+``bindgen`` 用來產生核心 C 語言端的 Rust 綁定，它依賴 ``libclang``。
+
+Make
+----
+
+建置核心需要 GNU make 4.0 或更新版本。
+
+Bash
+----
+
+核心建置過程會用到一些 bash 指令稿，需要 Bash 4.2 或更新版本。
+
+Binutils
+--------
+
+建置核心需要 Binutils 2.30 或更新版本。
+
+pkg-config
+----------
+
+從 4.18 開始，建置系統需要 pkg-config 來檢查已安裝的 kconfig 工具，並決定
+'make {g,x}config' 所用的旗標設定。在此之前雖然已經使用 pkg-config，但並
+沒有檢查，也沒有寫進文件。
+
+Flex
+----
+
+從 Linux 4.16 開始，建置系統會在建置期間產生詞法分析器，因此需要 flex
+2.5.35 或更新版本。
+
+
+Bison
+-----
+
+從 Linux 4.16 開始，建置系統會在建置期間產生剖析器，因此需要 bison
+2.0 或更新版本。
+
+pahole
+------
+
+從 Linux 5.2 開始，如果選擇了 CONFIG_DEBUG_INFO_BTF，建置系統會從 vmlinux
+的 DWARF 產生 BTF（BPF Type Format），稍後也會從核心模組產生。這需要
+pahole v1.22 或更新版本。
+
+可以在發行版的「dwarves」或「pahole」套件中找到它，或從
+https://fedorapeople.org/~acme/dwarves/ 取得。
+
+Perl
+----
+
+建置核心需要 perl 5 以及下列模組：``Getopt::Long``、``Getopt::Std``、
+``File::Basename`` 與 ``File::Find``。
+
+Python
+------
+
+有幾個設定選項需要它：arm/arm64 的預設設定、CONFIG_LTO_CLANG、某些 DRM
+選用設定、kernel-doc 工具，以及文件建置（Sphinx）等都需要 Python。
+
+BC
+--
+
+建置 3.10 及更新版本的核心需要 bc。
+
+
+OpenSSL
+-------
+
+模組簽章與外部憑證處理會使用 OpenSSL 程式與加密函式庫來產生金鑰與簽章。
+
+如果啟用了模組簽章，建置 3.7 及更新版本的核心需要 openssl。建置 4.3 及
+更新版本的核心還需要 openssl 的開發套件。
+
+Tar
+---
+
+如果要啟用透過 sysfs 存取核心標頭檔的功能（CONFIG_IKHEADERS），需要 GNU
+tar。
+
+gtags / GNU GLOBAL（選用）
+--------------------------
+
+核心建置需要 GNU GLOBAL 6.6.5 或更新版本，才能透過 ``make gtags`` 產生
+標籤檔，這是因為它用到 gtags 的 ``-C (--directory)`` 旗標。
+
+mkimage
+-------
+
+建置 Flat Image Tree（FIT）時會用到這個工具，FIT 常見於 ARM 平臺。這個
+工具可以從 ``u-boot-tools`` 套件取得，也可以從 U-Boot 原始碼建置。請參閱
+https://docs.u-boot.org/en/latest/build/tools.html#building-tools-for-linux
+的說明。
+
+GNU AWK
+-------
+
+如果要讓核心建置產生內建模組的位址範圍資料
+（CONFIG_BUILTIN_MODULE_RANGES），需要 GNU AWK。
+
+系統工具
+********
+
+架構上的變更
+------------
+
+DevFS 已經淘汰，改用 udev
+(https://www.kernel.org/pub/linux/utils/kernel/hotplug/)
+
+32 位元 UID 支援現在已經就緒。好好享受吧！
+
+Linux 函式的文件正逐步改為行內文件，也就是寫在原始碼中函式定義附近、具有
+特殊格式的註解。這些註解可以與 Documentation/ 目錄下的 ReST 檔案結合，
+產生內容更豐富的文件，再轉換成 PostScript、HTML、LaTex、ePUB 與 PDF 檔案。
+要把 ReST 格式轉換成你想要的格式，需要 Sphinx。
+
+Util-linux
+----------
+
+新版的 util-linux 讓 ``fdisk`` 支援更大的磁碟、為 mount 提供新的選項、
+能辨識更多種分割區類型，還有其他類似的好處。你大概會想升級。
+
+Ksymoops
+--------
+
+如果發生了難以想像的事，你的核心出現 oops，你可能需要用 ksymoops 工具來
+解碼，不過大多數情況下並不需要。一般建議在建置核心時啟用
+``CONFIG_KALLSYMS``，讓核心產生可以直接使用的可讀傾印（這也比 ksymoops
+的輸出更好）。如果因為某些原因，你的核心沒有啟用 ``CONFIG_KALLSYMS``，而
+你又沒辦法用該選項重新建置並重現 Oops，仍然可以用 ksymoops 解碼該 Oops。
+
+Mkinitrd
+--------
+
+``/lib/modules`` 檔案樹配置的這些變更，也需要升級 mkinitrd。
+
+E2fsprogs
+---------
+
+最新版的 ``e2fsprogs`` 修正了 fsck 與 debugfs 的幾個缺陷。顯然，升級是個
+好主意。
+
+JFSutils
+--------
+
+``jfsutils`` 套件包含這個檔案系統的工具程式，提供下列工具：
+
+- ``fsck.jfs`` - 啟動交易日誌的重播，並檢查與修復 JFS 格式的分割區。
+
+- ``mkfs.jfs`` - 建立 JFS 格式的分割區。
+
+- 這個套件裡也有其他檔案系統工具。
+
+Xfsprogs
+--------
+
+最新版的 ``xfsprogs`` 包含 XFS 檔案系統的 ``mkfs.xfs``、``xfs_db`` 與
+``xfs_repair`` 等工具。它與架構無關，2.0.0 以後的任何版本應該都能與這個
+版本的 XFS 核心程式碼正常搭配（建議使用 2.6.0 或更新版本，因為有一些重大
+改進）。
+
+PCMCIAutils
+-----------
+
+PCMCIAutils 取代了 ``pcmcia-cs``。如果核心採用模組化並使用熱插拔子系統，
+它會在系統啟動時正確設定 PCMCIA 插槽，並為 16 位元 PCMCIA 裝置載入適當的
+模組。
+
+Quota-tools
+-----------
+
+如果要使用較新的第 2 版 quota 格式，必須支援 32 位元的 uid 與 gid。
+Quota-tools 3.07 及更新版本提供這項支援。請使用上表建議的版本或更新版本。
+
+Intel IA32 微碼
+---------------
+
+核心已加入一個驅動程式，可以更新 Intel IA32 微碼，它是一個一般的（misc）
+字元裝置。如果你沒有使用 udev，在使用之前可能需要以 root 身分執行::
+
+ mkdir /dev/cpu
+ mknod /dev/cpu/microcode c 10 184
+ chmod 0644 /dev/cpu/microcode
+
+你大概也會想取得使用者空間的 microcode_ctl 工具來搭配使用。
+
+udev
+----
+
+``udev`` 是一個使用者空間應用程式，以動態方式在 ``/dev`` 中只建立實際存在
+的裝置項目。``udev`` 取代了 devfs 的基本功能，同時能為裝置提供固定的
+裝置名稱。
+
+FUSE
+----
+
+需要 libfuse 2.4.0 或更新版本。最低限度是 2.3.0，但 mount 選項
+``direct_io`` 與 ``kernel_cache`` 將無法使用。
+
+網路
+****
+
+一般變更
+--------
+
+如果你有進階的網路設定需求，或許應該考慮使用 ip-route2 的網路工具。
+
+封包過濾 / NAT
+--------------
+封包過濾與 NAT 程式碼使用的工具與之前的 2.4.x 核心系列相同（iptables）。
+它仍然包含與 2.2.x 風格的 ipchains 及 2.0.x 風格的 ipfwadm 向下相容的模組。
+
+PPP
+---
+
+PPP 驅動程式已經重新架構，以支援多重連結（multilink），並能在多種不同的
+媒介層上運作。如果你使用 PPP，請將 pppd 升級到至少 2.4.0。
+
+如果你沒有使用 udev，必須要有裝置檔案 /dev/ppp，可以以 root 身分執行下列
+指令建立::
+
+ mknod /dev/ppp c 108 0
+
+NFS-utils
+---------
+
+在古老的（2.4 及更早的）核心中，nfs 伺服器必須知道每個預期能透過 NFS 存取
+檔案的用戶端。這些資訊會在用戶端掛載檔案系統時由 ``mountd`` 提供給核心，
+或在系統啟動時由 ``exportfs`` 提供。exportfs 會從 ``/var/lib/nfs/rmtab``
+取得活動中用戶端的資訊。
+
+這種做法相當脆弱，因為它依賴 rmtab 的正確性，而這並不容易做到，特別是在
+嘗試實作容錯移轉（fail-over）時。即使系統運作正常，``rmtab`` 也會累積許多
+永遠不會被移除的舊項目。
+
+在現代的核心中，可以選擇讓核心在收到未知主機的請求時通知 mountd，再由
+mountd 把適當的匯出資訊提供給核心。這樣就不再依賴 ``rmtab``，而且核心只需
+要知道目前活動中的用戶端。
+
+要啟用這項新功能，需要在執行 exportfs 或 mountd 之前執行::
+
+ mount -t nfsd nfsd /proc/fs/nfsd
+
+建議盡可能用防火牆保護所有 NFS 服務，使其不暴露在整個網際網路上。
+
+mcelog
+------
+
+在 x86 核心上，啟用 ``CONFIG_X86_MCE`` 時需要 mcelog 工具來處理並記錄
+機器檢查事件。機器檢查事件是 CPU 回報的錯誤，強烈建議處理這些事件。
+
+核心文件
+********
+
+Sphinx
+------
+
+關於 Sphinx 需求的詳細資訊，請參閱 Documentation/doc-guide/sphinx.rst 中的
+:ref:`sphinx_install`。
+
+rustdoc
+-------
+
+``rustdoc`` 用來產生 Rust 程式碼的文件。更多資訊請參閱
+Documentation/rust/general-information.rst。
+
+取得更新的軟體
+==============
+
+核心編譯
+********
+
+gcc
+---
+
+- <ftp://ftp.gnu.org/gnu/gcc/>
+
+Clang/LLVM
+----------
+
+- :ref:`取得 LLVM <getting_llvm>`。
+
+Rust
+----
+
+- Documentation/rust/quick-start.rst。
+
+bindgen
+-------
+
+- Documentation/rust/quick-start.rst。
+
+Make
+----
+
+- <ftp://ftp.gnu.org/gnu/make/>
+
+Bash
+----
+
+- <ftp://ftp.gnu.org/gnu/bash/>
+
+Binutils
+--------
+
+- <https://www.kernel.org/pub/linux/devel/binutils/>
+
+Flex
+----
+
+- <https://github.com/westes/flex/releases>
+
+Bison
+-----
+
+- <ftp://ftp.gnu.org/gnu/bison/>
+
+OpenSSL
+-------
+
+- <https://www.openssl.org/>
+
+系統工具
+********
+
+Util-linux
+----------
+
+- <https://www.kernel.org/pub/linux/utils/util-linux/>
+
+Kmod
+----
+
+- <https://www.kernel.org/pub/linux/utils/kernel/kmod/>
+- <https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git>
+
+Ksymoops
+--------
+
+- <https://www.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/>
+
+Mkinitrd
+--------
+
+- <https://code.launchpad.net/initrd-tools/main>
+
+E2fsprogs
+---------
+
+- <https://www.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs/>
+- <https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git/>
+
+JFSutils
+--------
+
+- <https://jfs.sourceforge.net/>
+
+Xfsprogs
+--------
+
+- <https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git>
+- <https://www.kernel.org/pub/linux/utils/fs/xfs/xfsprogs/>
+
+Pcmciautils
+-----------
+
+- <https://www.kernel.org/pub/linux/utils/kernel/pcmcia/>
+
+Quota-tools
+-----------
+
+- <https://sourceforge.net/projects/linuxquota/>
+
+
+Intel P6 微碼
+-------------
+
+- <https://downloadcenter.intel.com/>
+
+udev
+----
+
+- <https://www.freedesktop.org/software/systemd/man/udev.html>
+
+FUSE
+----
+
+- <https://github.com/libfuse/libfuse/releases>
+
+mcelog
+------
+
+- <https://www.mcelog.org/>
+
+網路
+****
+
+PPP
+---
+
+- <https://download.samba.org/pub/ppp/>
+- <https://git.ozlabs.org/?p=ppp.git>
+- <https://github.com/paulusmack/ppp/>
+
+NFS-utils
+---------
+
+- <https://sourceforge.net/project/showfiles.php?group_id=14>
+- <https://nfs.sourceforge.net/>
+
+Iptables
+--------
+
+- <https://netfilter.org/projects/iptables/index.html>
+
+Ip-route2
+---------
+
+- <https://www.kernel.org/pub/linux/utils/net/iproute2/>
+
+OProfile
+--------
+
+- <https://oprofile.sf.net/download/>
+
+核心文件
+********
+
+Sphinx
+------
+
+- <https://www.sphinx-doc.org/>
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index 7b830c48942a..90c33d020d34 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -40,6 +40,7 @@
.. toctree::
:maxdepth: 1
+ changes
programming-language
coding-style
maintainer-pgp-guide
@@ -49,7 +50,6 @@
TODOList:
-* changes
* backporting
* adding-syscalls
* botching-up-ioctls
--
2.43.0
^ permalink raw reply [flat|nested] 14+ messages in thread* [PATCH 06/13] docs/zh_TW: process: add handling-regressions.rst translation
2026-11-06 11:35 [PATCH 00/13] docs/zh_TW: process: add translations of 13 documents Chen-Yu Yeh
` (4 preceding siblings ...)
2026-11-06 11:35 ` [PATCH 05/13] docs/zh_TW: process: add changes.rst translation Chen-Yu Yeh
@ 2026-11-06 11:35 ` Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 07/13] docs/zh_TW: process: add deprecated.rst translation Chen-Yu Yeh
` (6 subsequent siblings)
12 siblings, 0 replies; 14+ messages in thread
From: Chen-Yu Yeh @ 2026-11-06 11:35 UTC (permalink / raw)
To: Alex Shi, Jonathan Corbet
Cc: Weijie Yuan, Dongliang Mu, Yanteng Si, linux-doc, linux-kernel,
Chen-Yu Yeh
Translate Documentation/process/handling-regressions.rst into
Traditional Chinese from the current English text, including the
regzbot sections and the "Quotes from Linus about regression" section.
The quoted mails are kept in English as in the original literal
blocks. There is no zh_CN translation of this file to consult.
List the new file in the toctree of process/index.rst, after
debugging/index as in the English index, and drop it from the
TODOList.
update to commit fdd100ee60a0 ("docs: process: use gender-neutral
pronouns")
Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
.../zh_TW/process/handling-regressions.rst | 969 ++++++++++++++++++
.../translations/zh_TW/process/index.rst | 2 +-
2 files changed, 970 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_TW/process/handling-regressions.rst
diff --git a/Documentation/translations/zh_TW/process/handling-regressions.rst b/Documentation/translations/zh_TW/process/handling-regressions.rst
new file mode 100644
index 000000000000..54cfc5dda768
--- /dev/null
+++ b/Documentation/translations/zh_TW/process/handling-regressions.rst
@@ -0,0 +1,969 @@
+.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
+.. 重新散布的相關資訊請見本文件結尾。
+
+.. include:: ../disclaimer-zh_TW.rst
+
+:Original: Documentation/process/handling-regressions.rst
+
+處理迴歸問題
+++++++++++++
+
+*我們不製造迴歸* ——本文件說明這條「Linux 核心開發的首要規則」在實務上對
+開發者的意義。本文件是 Documentation/admin-guide/reporting-regressions.rst
+的補充，後者從使用者的角度說明這個主題；如果你從未讀過那份文件，請在繼續
+閱讀本文之前，至少先大致瀏覽一遍。
+
+重點摘要（亦即「TL;DR」）
+=========================
+
+#. 確保 `迴歸郵件列表 <https://lore.kernel.org/regressions/>`_
+ （regressions@lists.linux.dev）的訂閱者能盡快得知任何新的迴歸報告：
+
+ * 收到沒有抄送（CC）該列表的郵件報告時，立即至少發送一封簡短的
+ 「全部回覆」（Reply-all）並抄送該列表，讓列表參與其中。
+
+ * 把提交到缺陷追蹤器的報告轉寄或退回（bounce）到該列表。
+
+#. 讓 Linux 核心迴歸追蹤機器人「regzbot」追蹤這個問題（此步驟可選，但建議
+ 這麼做）：
+
+ * 對於郵件報告，檢查報告者是否附上了類似 ``#regzbot
+ introduced: v5.13..v5.14-rc1`` 的一行。如果沒有，請發送一封回覆（抄送
+ 迴歸列表），其中包含類似下面的段落，告訴 regzbot 問題從何時開始發生::
+
+ #regzbot ^introduced: 1f2e3d4c5b6a
+
+ * 把缺陷追蹤器中的報告轉寄到迴歸列表時（見上文），請附上類似下面的
+ 段落::
+
+ #regzbot introduced: v5.13..v5.14-rc1
+ #regzbot from: Some N. Ice Human <some.human@example.com>
+ #regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789
+
+#. 提交迴歸的修正時，依照 Documentation/process/submitting-patches.rst 與
+ :ref:`Documentation/process/5.Posting.rst <tw_development_posting>` 的要求，
+ 在修補程式描述中加上「Closes:」標籤，指向所有回報該問題的地方。如果你
+ 只修正了造成迴歸之問題的一部分，可以改用「Link:」標籤。regzbot 目前
+ 不區分這兩者。
+
+#. 一旦找出肇事提交（culprit），請盡快修復迴歸；大多數迴歸的修正應在兩週
+ 內合併，但有些需要在兩到三天內解決。
+
+
+與開發者相關的 Linux 核心迴歸完整細節
+=====================================
+
+
+重要基本事項詳述
+----------------
+
+
+收到迴歸報告時該怎麼做
+~~~~~~~~~~~~~~~~~~~~~~
+
+確保 Linux 核心的迴歸追蹤者以及
+`迴歸郵件列表 <https://lore.kernel.org/regressions/>`_
+（regressions@lists.linux.dev）的其他訂閱者得知任何新回報的迴歸：
+
+ * 如果你收到的郵件報告沒有抄送該列表，請立即至少發送一封簡短的「全部
+ 回覆」並抄送該列表，讓列表參與其中；如果你回覆的郵件漏掉了該列表，
+ 也請設法確保再次抄送它。
+
+ * 如果提交到缺陷追蹤器的報告出現在你的收件匣中，請把它轉寄或退回到該
+ 列表。轉寄之前，不妨先查看列表的封存，確認報告者是否已經依照
+ Documentation/admin-guide/reporting-issues.rst 的指示轉寄過該報告。
+
+進行上述任一動作時，可以考慮讓 Linux 核心迴歸追蹤機器人「regzbot」立即
+開始追蹤這個問題：
+
+ * 對於郵件報告，檢查報告者是否附上了類似
+ ``#regzbot introduced: 1f2e3d4c5b6a`` 的「regzbot 命令」。如果沒有，
+ 請發送一封回覆（抄送迴歸列表），其中包含類似下面的段落::
+
+ #regzbot ^introduced: v5.13..v5.14-rc1
+
+ 這會告訴 regzbot 問題開始發生的版本範圍；你也可以用 commit ID 指定
+ 範圍，或在報告者已用二分法找出肇事提交時，只指定單一 commit ID。
+
+ 請注意「introduced」前面的插入符號（^）：它告訴 regzbot 把上層郵件
+ （你所回覆的那封）當作你想追蹤之迴歸的初始報告；這一點很重要，因為
+ regzbot 之後會尋找帶有「Closes:」標籤、指向 lore.kernel.org 封存中
+ 該報告的修補程式。
+
+ * 轉寄回報到缺陷追蹤器的迴歸時，請附上包含下列 regzbot 命令的段落::
+
+ #regzbot introduced: 1f2e3d4c5b6a
+ #regzbot from: Some N. Ice Human <some.human@example.com>
+ #regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789
+
+ 之後，regzbot 就會自動把帶有「Closes:」標籤、指向你的郵件或上述工單
+ 的修補程式與該報告關聯起來。
+
+修復迴歸時的要點
+~~~~~~~~~~~~~~~~
+
+提交迴歸的修正時不需要做任何特別的事，只要記得照著
+Documentation/process/submitting-patches.rst、
+:ref:`Documentation/process/5.Posting.rst <tw_development_posting>` 與
+Documentation/process/stable-kernel-rules.rst 中已更詳細說明的做法即可：
+
+ * 使用「Closes:」標籤指向所有回報該問題的地方::
+
+ Closes: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
+ Closes: https://bugzilla.kernel.org/show_bug.cgi?id=1234567890
+
+ 如果你只修正了問題的一部分，可以依照上述第一份文件的說明改用「Link:」。
+ regzbot 目前把兩者視為相同，並將所連結的報告視為已解決。
+
+ * 加上「Fixes:」標籤，指出造成迴歸的提交。
+
+ * 如果肇事提交是在較早的開發週期中合併的，請使用
+ ``Cc: stable@vger.kernel.org`` 標籤，明確標記此修正需要向後移植。
+
+以上這些都是對你的期望，且在處理迴歸時十分重要，因為這些標籤對每個可能在
+數週、數月甚至數年後研究這個問題的人（包括你自己）都非常有價值。這些標籤
+對其他核心開發者或 Linux 發行版所使用的工具和腳本也至關重要；regzbot 就是
+其中之一，它高度依賴「Closes:」標籤，把迴歸報告與解決它們的變更關聯起來。
+
+修復迴歸的期望與最佳實務
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+身為 Linux 核心開發者，你應該盡最大努力，避免讓你最近的變更所造成的迴歸
+使使用者只剩下以下選擇：
+
+ * 執行一個帶有影響使用之迴歸的核心。
+
+ * 改用較舊或較新的核心系列。
+
+ * 在找出迴歸的肇事提交後，繼續執行過時、因而可能不安全的核心超過三週。
+ 理想情況下應少於兩週。而如果問題嚴重或影響許多使用者（無論是整體而言，
+ 還是在普遍的環境中），則應該只有短短幾天。
+
+實務上如何做到這一點取決於各種因素。請以下列經驗法則作為指引。
+
+一般而言：
+
+ * 將迴歸的處理優先於所有其他 Linux 核心工作，除非後者涉及嚴重問題（例如
+ 緊急的安全漏洞、資料遺失、硬體變磚……）。
+
+ * 加速修復最近進入正式主線、穩定版或長期支援版發布（無論是直接進入還是
+ 經由向後移植）的主線迴歸。
+
+ * 不要把目前週期中的迴歸當作可以等到週期結束再處理的事情，因為這個問題
+ 可能讓使用者和 CI 系統現在或往後都不願或無法測試主線。
+
+ * 以必要的謹慎進行工作，避免造成額外或更大的損害，即使這樣解決問題可能
+ 會比下文所述花費更長的時間。
+
+找出迴歸的肇事提交之後，關於時程：
+
+ * 如果問題嚴重或困擾許多使用者（無論是整體而言，還是在特定硬體環境、
+ 發行版或穩定版／長期支援版系列等普遍情況下），目標是在兩到三天內將修正
+ 合併進主線。
+
+ * 如果肇事提交進入了最近的主線、穩定版或長期支援版發布（無論是直接進入
+ 還是經由向後移植），目標是在下下個星期日之前將修正合併進主線；如果
+ 肇事提交在一週的前段就已確認且容易解決，請盡量在同一週內將修正合併進
+ 主線。
+
+ * 對於其他迴歸，目標是在接下來三週內的最後一個星期日之前將修正合併進
+ 主線。如果該迴歸是人們可以輕鬆忍受一段時間的問題（例如輕微的效能迴歸），
+ 延後一到兩個星期日也可以接受。
+
+ * 強烈不建議把迴歸修正延到下一個合併視窗才合併進主線，除非該修正的風險
+ 極高，或肇事提交是在一年多以前合併進主線的。
+
+關於流程：
+
+ * 一定要考慮撤銷（revert）肇事提交，因為這通常是修復迴歸最快、危險最小
+ 的方式。不必擔心之後把修正過的版本合併進主線：這應該很直接，因為大部分
+ 程式碼都已經審查過一次。
+
+ * 盡量在目前的開發週期結束前，解決過去十二個月內在主線中引入的任何迴歸：
+ Linus 希望這類迴歸能像目前週期中的迴歸一樣處理，除非修復它們有不尋常
+ 的風險。
+
+ * 如果迴歸看起來很棘手，可以考慮在討論或修補程式審查中抄送 Linus。在危急
+ 或緊急的情況下也這麼做，特別是子系統維護者可能無法聯繫時。當你知道這類
+ 迴歸已進入主線、穩定版或長期支援版發布時，也請抄送穩定版團隊。
+
+ * 對於緊急的迴歸，可以考慮請 Linus 直接從郵件列表取用修正：對於沒有爭議
+ 的修正，他完全可以接受這種做法。不過理想情況下，這類請求應該與子系統
+ 維護者協調一致，或直接由他們提出。
+
+ * 如果你不確定在新的主線版本發布前幾天套用某個修正是否值得冒險，請寄一封
+ 郵件給 Linus，並照常抄送相關列表與人員；在郵件中概述情況，同時請他考慮
+ 直接從列表取用該修正。之後他可以自己做出決定，必要時甚至可以延後發布。
+ 同樣地，這類請求理想上應該與子系統維護者協調一致，或直接由他們提出。
+
+關於穩定版與長期支援版核心：
+
+ * 如果迴歸從未在主線中出現過，或已經在主線中修復，你可以把它們留給穩定版
+ 團隊處理。
+
+ * 如果某個迴歸在過去十二個月內進入了正式的主線發布，請務必在修正中加上
+ 「Cc: stable@vger.kernel.org」標籤，因為單靠「Fixes:」標籤並不能保證會
+ 被向後移植。如果你知道肇事提交已被向後移植到穩定版或長期支援版核心，
+ 也請加上同樣的標籤。
+
+ * 收到最近的穩定版或長期支援版核心系列的迴歸報告時，請至少簡單評估一下
+ 該問題是否也可能發生在目前的主線中；如果看起來很可能，請接手處理該報告。
+ 如有疑問，請報告者在主線上檢查。
+
+ * 每當你想迅速解決一個最近也進入了正式主線、穩定版或長期支援版發布的迴歸
+ 時，請在主線中盡快修復它；在適當的時候，請 Linus 協助加速處理這個修正
+ （見上文）。這是因為穩定版團隊通常既不撤銷、也不修復在主線中造成相同
+ 問題的變更。
+
+ * 對於緊急的迴歸修正，你可能會想在修正合併進主線後，給穩定版團隊留個訊息，
+ 以確保它盡快被向後移植；在合併視窗期間及其後不久特別建議這麼做，否則該
+ 修正可能會排在一個龐大的修補程式佇列的最後面。
+
+關於修補程式的流程：
+
+ * 開發者們，在設法達成上述時限時，請記得把修正接受測試、審查以及被 Linus
+ 合併所需的時間計算在內，理想情況下修正至少要在 linux-next 中待上一小段
+ 時間。因此，如果某個修正很緊急，請明確表示出來，確保其他人適當地處理它。
+
+ * 審查者們，懇請你們及時審查迴歸修正，協助開發者達成上述時限。
+
+ * 子系統維護者們，同樣也鼓勵你們加速處理迴歸修正。因此，請評估對於特定的
+ 修正是否可以跳過 linux-next。必要時也可以考慮比平常更頻繁地發送 git 拉取
+ 請求。並且盡量避免在週末把迴歸修正壓著不處理，特別是當該修正被標記為需要
+ 向後移植時。
+
+
+開發者應該留意的其他迴歸相關面向
+--------------------------------
+
+
+如何處理已知有迴歸風險的變更
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+評估迴歸風險有多大，例如在 Linux 發行版和 Git 託管平台（forge）中搜尋
+程式碼。也可以考慮請可能受影響的其他開發者或專案評估、甚至測試所提議的
+變更；如果出現問題，或許可以找到所有人都能接受的解決方案。
+
+如果最後看來迴歸風險相對較小，就繼續進行這個變更，但要讓所有相關人員知道
+這個風險。因此，請確保你的修補程式描述清楚說明這一點。變更合併後，請告知
+Linux 核心的迴歸追蹤者和迴歸郵件列表這個風險，讓大家在有報告陸續出現時都
+已注意到這個變更。視風險而定，你可能也會想請子系統維護者在他們的主線拉取
+請求中提及這個問題。
+
+關於迴歸還有什麼需要知道的？
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+請參閱 Documentation/admin-guide/reporting-regressions.rst，其中涵蓋了許多
+你可能想要了解的其他面向：
+
+ * 「無迴歸」規則的目的
+
+ * 哪些問題真正算是迴歸
+
+ * 誰負責找出迴歸的根本原因
+
+ * 如何處理棘手的情況，例如迴歸是由安全修正所造成，或修復某個迴歸可能造成
+ 另一個迴歸
+
+遇到迴歸時可以向誰尋求建議
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+寄一封郵件到迴歸郵件列表（regressions@lists.linux.dev），同時抄送 Linux
+核心的迴歸追蹤者（regressions@leemhuis.info）；如果問題比較適合私下處理，
+可以省略該列表。
+
+
+關於迴歸追蹤與 regzbot 的更多資訊
+---------------------------------
+
+
+為什麼 Linux 核心有迴歸追蹤者？為什麼要使用 regzbot？
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+像「無迴歸」這樣的規則需要有人確保它被遵守，否則就會因意外或刻意而遭到
+破壞。歷史已經證明，這對 Linux 核心來說也是如此。因此 Thorsten Leemhuis
+自願擔任 Linux 核心的迴歸追蹤者來留意這些事，偶爾也有其他人協助。他們都
+沒有因此獲得報酬，所以迴歸追蹤是盡力而為的。
+
+先前手動追蹤迴歸的嘗試顯示，這是一項令人筋疲力盡又沮喪的工作，因此在一段
+時間後就被放棄了。為了避免這種情況再次發生，Thorsten 開發了 regzbot 來協助
+這項工作，長期目標是盡可能為所有相關人員自動化迴歸追蹤。
+
+regzbot 如何進行迴歸追蹤？
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+這個機器人會留意已追蹤迴歸的報告所收到的回覆。此外，它也會尋找以
+「Closes:」標籤引用這些報告、已發布或已提交（commit）的修補程式；對這些
+修補程式貼文的回覆也會被追蹤。綜合這些資料，就能清楚了解修復過程目前的
+狀態。
+
+regzbot 盡量以最少的額外負擔為報告者和開發者完成工作。事實上，只有報告者
+多了一項額外的責任：他們需要使用上述的 ``#regzbot introduced`` 命令，把
+迴歸報告告知 regzbot；如果他們沒有這麼做，其他人可以使用
+``#regzbot ^introduced`` 代為處理。
+
+對開發者而言，通常不需要額外的工作，只需要確實做到早在 regzbot 出現之前
+就被期望做的事：在修補程式描述中加上連結，指向所有關於所修復問題的報告。
+
+我一定要使用 regzbot 嗎？
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+如果你使用，這對所有人都有好處，因為像 Linus Torvalds 這樣的核心維護者在
+工作中部分依賴 regzbot 的追蹤，例如在決定要發布新版本或延長開發階段時。
+為此，他們需要知道所有尚未修復的迴歸；眾所周知，Linus 會查看 regzbot 每週
+發送的報告。
+
+我一定要把遇到的每個迴歸都告訴 regzbot 嗎？
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+理想上是的：我們都是凡人，當更重要的事情突然出現時很容易忘記問題，例如
+Linux 核心中更大的問題，或是現實生活中讓我們有一陣子無法碰鍵盤的事情。
+因此，最好把每個迴歸都告訴 regzbot，除非你立即寫出修正，並把它提交到一個
+會定期合併到受影響核心系列的樹中。
+
+如何查看 regzbot 目前追蹤哪些迴歸？
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+請查看 `regzbot 的網頁介面 <https://linux-regtracking.leemhuis.info/regzbot/>`_
+以取得最新資訊；或者，`搜尋最新的迴歸報告
+<https://lore.kernel.org/lkml/?q=%22Linux+regressions+report%22+f%3Aregzbot>`_，
+regzbot 通常每週日晚上（UTC）發送一次這份報告，也就是 Linus 通常發布新的
+版本或預發布版本的幾個小時之前。
+
+regzbot 監看哪些地方？
+~~~~~~~~~~~~~~~~~~~~~~
+
+regzbot 會監看最重要的 Linux 郵件列表，以及 linux-next、主線和穩定版／
+長期支援版的 git 儲存庫。
+
+哪些問題應該由 regzbot 追蹤？
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+這個機器人是用來追蹤迴歸的，因此請不要讓 regzbot 處理一般問題。不過，如果
+你用 regzbot 追蹤嚴重的問題，例如卡死（hang）、資料損毀或內部錯誤（Panic、
+Oops、BUG()、warning……）的報告，Linux 核心的迴歸追蹤者也可以接受。
+
+可以把 CI 系統發現的迴歸加入 regzbot 的追蹤嗎？
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+可以，只要該迴歸很可能影響實際的使用情境，因而可能被使用者注意到即可；
+因此，請不要讓 regzbot 處理不太可能在實際使用中出現的理論上的迴歸。
+
+如何與 regzbot 互動？
+~~~~~~~~~~~~~~~~~~~~~
+
+在直接或間接回覆迴歸報告郵件時使用「regzbot 命令」。這些命令必須自成一個
+段落（換句話說：必須用空行與郵件的其他內容分隔開）。
+
+其中一個命令是 ``#regzbot introduced: <version or commit>``，如前所述，它會
+讓 regzbot 把你的郵件視為一份加入追蹤的迴歸報告；另一個這樣的命令是
+``#regzbot ^introduced: <version or commit>``，它會讓 regzbot 把上層郵件
+視為一份迴歸報告並開始追蹤。
+
+一旦使用了這兩個命令之一，就可以在直接或間接回覆該報告時使用其他 regzbot
+命令。你可以把它們寫在某個 `introduced` 命令的下方，或寫在回覆以下郵件的
+郵件中：使用了其中一個命令的郵件，或本身是回覆該郵件的郵件：
+
+ * 設定或更新標題::
+
+ #regzbot title: foo
+
+ * 監看討論該問題其他面向或修正的討論串或 bugzilla.kernel.org 工單，例如
+ 修復該迴歸的修補程式貼文::
+
+ #regzbot monitor: https://lore.kernel.org/all/30th.anniversary.repost@klaava.Helsinki.FI/
+
+ 監看功能只適用於 lore.kernel.org 和 bugzilla.kernel.org；regzbot 會把
+ 該討論串或工單中的所有訊息都視為與修復過程有關。
+
+ * 指向一個有其他值得注意之細節的地方，例如稍微相關、但主題不同的郵件列表
+ 貼文或缺陷追蹤器中的工單::
+
+ #regzbot link: https://bugzilla.kernel.org/show_bug.cgi?id=123456789
+
+ * 將迴歸標記為已由某個正在送往上游或已經合併的提交修復::
+
+ #regzbot fix: 1f2e3d4c5d
+
+ * 將迴歸標記為另一個已由 regzbot 追蹤之迴歸的重複::
+
+ #regzbot dup-of: https://lore.kernel.org/all/30th.anniversary.repost@klaava.Helsinki.FI/
+
+ * 將迴歸標記為無效::
+
+ #regzbot invalid: wasn't a regression, problem has always existed
+
+關於 regzbot 及其命令還有更多資訊嗎？
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+關於 Linux 核心迴歸追蹤機器人更詳細且最新的資訊，可以在它的
+`專案頁面 <https://gitlab.com/knurd42/regzbot>`_ 找到，其中包括
+`入門指南 <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/getting_started.md>`_
+和 `參考文件 <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md>`_，
+兩者涵蓋的細節都比上面這一節更多。
+
+Linus 關於迴歸的發言
+--------------------
+
+以下是 Linus Torvalds 的一些發言，有助於了解 Linux 的「無迴歸」規則，以及
+他期望如何處理迴歸：
+
+迴歸應該多快修復
+~~~~~~~~~~~~~~~~
+
+* 出自 `2026-01-22 <https://lore.kernel.org/all/CAHk-=wheQNiW_WtHGO7bKkT7Uib-p+ai2JP9M+z+FYcZ6CAxYA@mail.gmail.com/>`_::
+
+ But a user complaining should basically result in an immediate fix -
+ possibly a "revert and rethink".
+
+ 稍後在 `2026-01-28 <https://lore.kernel.org/all/CAHk-%3Dwi86AosXs66-yi54%2BmpQjPu0upxB8ZAfG%2BLsMyJmcuMSA@mail.gmail.com/>`_ 又進一步說明::
+
+ It's also worth noting that "immediate" obviously doesn't mean "right
+ this *second* when the problem has been reported".
+
+ But if it's a regression with a known commit that caused it, I think
+ the rule of thumb should generally be "within a week", preferably
+ before the next rc.
+
+* 出自 `2023-04-21 <https://lore.kernel.org/all/CAHk-=wgD98pmSK3ZyHk_d9kZ2bhgN6DuNZMAJaV0WTtbkf=RDw@mail.gmail.com/>`_::
+
+ Known-broken commits either
+ (a) get a timely fix that doesn't have other questions
+ or
+ (b) get reverted
+
+* 出自 `2021-09-20(2) <https://lore.kernel.org/all/CAHk-=wgOvmtRw1TNbMC1rn5YqyTKyn0hz+sc4k0DGNn++u9aYw@mail.gmail.com/>`_::
+
+ [...] review shouldn't hold up reported regressions of existing code. That's
+ just basic _testing_ - either the fix should be applied, or - if the fix is
+ too invasive or too ugly - the problematic source of the regression should
+ be reverted.
+
+ Review should be about new code, it shouldn't be holding up "there's a
+ bug report, here's the obvious fix".
+
+* 出自 `2023-05-08 <https://lore.kernel.org/all/CAHk-=wgzU8_dGn0Yg+DyX7ammTkDUCyEJ4C=NvnHRhxKWC7Wpw@mail.gmail.com/>`_::
+
+ If something doesn't even build, it should damn well be fixed ASAP.
+
+以撤銷來修復迴歸如何有助於避免維護者過勞
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* 出自 `2026-01-28 <https://lore.kernel.org/all/CAHk-%3Dwi86AosXs66-yi54%2BmpQjPu0upxB8ZAfG%2BLsMyJmcuMSA@mail.gmail.com/>`_::
+
+ > So how can I/we make "immediate fixes" happen more often without
+ > contributing to maintainer burnout?
+
+ [...] the "revert and rethink" model [...] often a good idea in general [...]
+
+ Exactly so that maintainers don't get stressed out over having a pending
+ problem report that people keep pestering them about.
+
+ I think people are sometimes a bit too bought into whatever changes
+ they made, and reverting is seen as "too drastic", but I think it's
+ often the quick and easy solution for when there isn't some obvious
+ response to a regression report.
+
+最後一個 -rc 或新版本即將發布時，將修正合併進主線
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* 出自 `2026-02-01 <https://lore.kernel.org/all/CAHk-%3DwhXTw1oPsa%2BTLuY1Rc9D1OAiPVOdR_-R2xG45kwDObKdA@mail.gmail.com/>`_::
+
+ So I think I'd rather see them hit rc8 (later today) and have a week
+ of testing in my tree and be reverted if they cause problems, than
+ have them go in after rc8 and then cause problems in the 6.19 release
+ instead.
+
+* 出自 `2023-04-20 <https://lore.kernel.org/all/CAHk-=wis_qQy4oDNynNKi5b7Qhosmxtoj1jxo5wmB6SRUwQUBQ@mail.gmail.com/>`_::
+
+ But something like this, where the regression was in the previous release
+ and it's just a clear fix with no semantic subtlety, I consider to be just a
+ regular regression that should be expedited - partly to make it into stable,
+ and partly to avoid having to put the fix into _another_ stable kernel.
+
+只為單一修正發送合併請求
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+* 出自 `2024-04-24 <https://lore.kernel.org/all/CAHk-=wjy_ph9URuFt-pq+2AJ__p7gFDx=yzVSCsx16xAYvNw9g@mail.gmail.com/>`_::
+
+ If the issue is just that there's nothing else happening, I think people
+ should just point me to the patch and say "can you apply this single fix?"
+
+* 出自 `2023-04-20 <https://lore.kernel.org/all/CAHk-=wis_qQy4oDNynNKi5b7Qhosmxtoj1jxo5wmB6SRUwQUBQ@mail.gmail.com/>`_::
+
+ I'm always open to direct fixes when there is no controversy about the fix.
+ No problem. I still happily deal with individual patches.
+
+使用 Link:/Closes: 標籤指向缺陷報告的重要性
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* 出自 `2025-07-29(1) <https://lore.kernel.org/all/CAHk-=wj2kJRPWx8B09AAtzj+_g+T6UBX11TP0ebs1WJdTtv=WQ@mail.gmail.com/>`_::
+
+ [...] revert like this, it really would be good to link to the problems, so
+ that when people try to re-enable it, they have the history for why it
+ didn't work the first time.
+
+* 出自 `2022-05-08 <https://lore.kernel.org/all/CAHk-=wjMmSZzMJ3Xnskdg4+GGz=5p5p+GSYyFBTh0f-DgvdBWg@mail.gmail.com/>`_::
+
+ So I have to once more complain [...]
+
+ [...] There's no link to the actual problem the patch fixes.
+
+* 出自 `2022-06-22 <https://lore.kernel.org/all/CAHk-=wjxzafG-=J8oT30s7upn4RhBs6TX-uVFZ5rME+L5_DoJA@mail.gmail.com/>`_::
+
+ See, *that* link [to the report] would have been useful in the commit.
+
+為什麼會有「無迴歸」規則
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+* 出自 `2026-01-22 <https://lore.kernel.org/all/CAHk-=wheQNiW_WtHGO7bKkT7Uib-p+ai2JP9M+z+FYcZ6CAxYA@mail.gmail.com/>`_::
+
+ But the basic rule is: be so good about backwards compatibility that
+ users never have to worry about upgrading. They should absolutely feel
+ confident that any kernel-reported problem will either be solved, or
+ have an easy solution that is appropriate for *them* (ie a
+ non-technical user shouldn't be expected to be able to do a lot).
+
+ Because the last thing we want is people holding back from trying new
+ kernels.
+
+* 出自 `2024-05-28 <https://lore.kernel.org/all/CAHk-=wgtb7y-bEh7tPDvDWru7ZKQ8-KMjZ53Tsk37zsPPdwXbA@mail.gmail.com/>`_::
+
+ I introduced that "no regressions" rule something like two decades
+ ago, because people need to be able to update their kernel without
+ fear of something they relied on suddenly stopping to work.
+
+* 出自 `2018-08-03 <https://lore.kernel.org/all/CA+55aFwWZX=CXmWDTkDGb36kf12XmTehmQjbiMPCqCRG2hi9kw@mail.gmail.com/>`_::
+
+ The whole point of "we do not regress" is so that people can upgrade
+ the kernel and never have to worry about it.
+
+ [...]
+
+ Because the only thing that matters IS THE USER.
+
+* 出自 `2017-10-26(1) <https://lore.kernel.org/lkml/CA+55aFxW7NMAMvYhkvz1UPbUTUJewRt6Yb51QAx5RtrWOwjebg@mail.gmail.com/>`_::
+
+ If the kernel used to work for you, the rule is that it continues to work
+ for you.
+
+ [...]
+
+ People should basically always feel like they can update their kernel
+ and simply not have to worry about it.
+
+ I refuse to introduce "you can only update the kernel if you also
+ update that other program" kind of limitations. If the kernel used to
+ work for you, the rule is that it continues to work for you.
+
+「無迴歸」規則的例外
+~~~~~~~~~~~~~~~~~~~~
+
+* 出自 `2026-01-22 <https://lore.kernel.org/all/CAHk-=wheQNiW_WtHGO7bKkT7Uib-p+ai2JP9M+z+FYcZ6CAxYA@mail.gmail.com/>`_::
+
+ There are _very_ few exceptions to that rule, the main one being "the
+ problem was a fundamental huge and gaping security issue and we *had* to
+ make that change, and we couldn't even make your limited use-case just
+ continue to work".
+
+ The other exception is "the problem was reported years after it was
+ introduced, and now most people rely on the new behavior".
+
+ [...]
+
+ Now, if it's one or two users and you can just get them to recompile,
+ that's one thing. Niche hardware and odd use-cases can sometimes be
+ solved that way, and regressions can sometimes be fixed by handholding
+ every single reporter if the reporter is willing and able to change
+ his or her workflow.
+
+* 出自 `2023-04-20 <https://lore.kernel.org/all/CAHk-=wis_qQy4oDNynNKi5b7Qhosmxtoj1jxo5wmB6SRUwQUBQ@mail.gmail.com/>`_::
+
+ And yes, I do consider "regression in an earlier release" to be a
+ regression that needs fixing.
+
+ There's obviously a time limit: if that "regression in an earlier
+ release" was a year or more ago, and just took forever for people to
+ notice, and it had semantic changes that now mean that fixing the
+ regression could cause a _new_ regression, then that can cause me to
+ go "Oh, now the new semantics are what we have to live with".
+
+* 出自 `2017-10-26(2) <https://lore.kernel.org/lkml/CA+55aFxW7NMAMvYhkvz1UPbUTUJewRt6Yb51QAx5RtrWOwjebg@mail.gmail.com/>`_::
+
+ There have been exceptions, but they are few and far between, and they
+ generally have some major and fundamental reasons for having happened,
+ that were basically entirely unavoidable, and people _tried_hard_ to
+ avoid them. Maybe we can't practically support the hardware any more
+ after it is decades old and nobody uses it with modern kernels any
+ more. Maybe there's a serious security issue with how we did things,
+ and people actually depended on that fundamentally broken model. Maybe
+ there was some fundamental other breakage that just _had_ to have a
+ flag day for very core and fundamental reasons.
+
+更新使用者空間的某些東西即可解決迴歸的情況
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* 出自 `2018-08-03 <https://lore.kernel.org/all/CA+55aFwWZX=CXmWDTkDGb36kf12XmTehmQjbiMPCqCRG2hi9kw@mail.gmail.com/>`_::
+
+ And dammit, we upgrade the kernel ALL THE TIME without upgrading any
+ other programs at all. It is absolutely required, because flag-days
+ and dependencies are horribly bad.
+
+ And it is also required simply because I as a kernel developer do not
+ upgrade random other tools that I don't even care about as I develop the
+ kernel, and I want any of my users to feel safe doing the same time.
+
+* 出自 `2017-10-26(3) <https://lore.kernel.org/lkml/CA+55aFxW7NMAMvYhkvz1UPbUTUJewRt6Yb51QAx5RtrWOwjebg@mail.gmail.com/>`_::
+
+ But if something actually breaks, then the change must get fixed or
+ reverted. And it gets fixed in the *kernel*. Not by saying "well, fix your
+ user space then". It was a kernel change that exposed the problem, it needs
+ to be the kernel that corrects for it, because we have a "upgrade in place"
+ model. We don't have a "upgrade with new user space".
+
+ And I seriously will refuse to take code from people who do not understand
+ and honor this very simple rule.
+
+ This rule is also not going to change.
+
+ And yes, I realize that the kernel is "special" in this respect. I'm proud
+ of it.
+
+* 出自 `2017-10-26(4) <https://lore.kernel.org/all/CA+55aFwiiQYJ+YoLKCXjN_beDVfu38mg=Ggg5LFOcqHE8Qi7Zw@mail.gmail.com/>`_::
+
+ If you break existing user space setups THAT IS A REGRESSION.
+
+ It's not ok to say "but we'll fix the user space setup".
+
+ Really. NOT OK.
+
+什麼算是使用者空間介面、ABI、API、有文件記載的介面等
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* 出自 `2026-01-20 <https://lore.kernel.org/all/CAHk-=wga8Qu0-OSE9VZbviq9GuqwhPhLUXeAt-S7_9+fMCLkKg@mail.gmail.com/>`_::
+
+ So I absolutely detest the whole notion of "ABI changes". It's a
+ meaningless concept, and I hate it with a passion, [...]
+
+ The Linux rule for regressions is basically based on the philosophical
+ question of "If a tree falls in the forest, and nobody is around to
+ hear it, does it make a sound?".
+
+ So the only thing that matters is if something breaks user-*conscious*
+ behavior.
+
+ And when that happens, the distinction between "bug fix" and "new
+ feature" and "ABI change" matters not one whit, and the change needs
+ to be done differently.
+
+ [...]
+
+ I just wanted to point out that the argument about whether it's an ABI
+ change or not is irrelevant. If it turns out that some program - not a test
+ script, but something with relevance to conscious user expectations ~
+ depended on the old broken behavior, then it needs to be done some other
+ way.
+
+* 出自 `2026-02-13 <https://lore.kernel.org/all/CAHk-=whY-N8kjm8kiFUV5Ei-8AuYw--EPGD-AR3Pd+5GTx2sAQ@mail.gmail.com/>`_::
+
+ > [...] this should not fall under the don't break user space rule [...]
+
+ Note that the rule is about breaking *users*, not breaking user space per
+ se. [...]
+
+ If some user setup breaks, things need fixing.
+
+ [...] but I want to make it very clear that there are no excuses about "user
+ space applications".
+
+* 出自 `2021-09-20(4) <https://lore.kernel.org/all/CAHk-=wi7DB2SJ-wngVvsJ7Ak2cM556Q8437sOXo4EJt2BWPdEg@mail.gmail.com/>`_::
+
+ [...] a regression is a bit like Schrödinger's cat - if nobody is around
+ to notice it and it doesn't actually affect any real workload, then you
+ can treat the regression as if it doesn't exist.
+
+* 出自 `2020-05-21 <https://lore.kernel.org/all/CAHk-=wiVi7mSrsMP=fLXQrXK_UimybW=ziLOwSzFTtoXUacWVQ@mail.gmail.com/>`_::
+
+ The rules about regressions have never been about any kind of documented
+ behavior, or where the code lives.
+
+ The rules about regressions are always about "breaks user workflow".
+
+ Users are literally the _only_ thing that matters.
+
+* 出自 `2019-09-15 <https://lore.kernel.org/lkml/CAHk-=wiP4K8DRJWsCo=20hn_6054xBamGKF2kPgUzpB5aMaofA@mail.gmail.com/>`_::
+
+ One _particularly_ last-minute revert is the top-most commit (ignoring
+ the version change itself) done just before the release, and while
+ it's very annoying, it's perhaps also instructive.
+
+ What's instructive about it is that I reverted a commit that wasn't
+ actually buggy. In fact, it was doing exactly what it set out to do,
+ and did it very well. In fact it did it _so_ well that the much
+ improved IO patterns it caused then ended up revealing a user-visible
+ regression due to a real bug in a completely unrelated area.
+
+ The actual details of that regression are not the reason I point that
+ revert out as instructive, though. It's more that it's an instructive
+ example of what counts as a regression, and what the whole "no
+ regressions" kernel rule means.
+
+ [...] The reverted commit didn't change any API's, and it didn't introduce
+ any new bugs. But it ended up exposing another problem, and as such caused
+ a kernel upgrade to fail for a user. So it got reverted.
+
+ The point here being that we revert based on user-reported _behavior_, not
+ based on some "it changes the ABI" or "it caused a bug" concept. The problem
+ was really pre-existing, and it just didn't happen to trigger before. [...]
+
+ Take-away from the whole thing: it's not about whether you change the
+ kernel-userspace ABI, or fix a bug, or about whether the old code
+ "should never have worked in the first place". It's about whether
+ something breaks existing users' workflow.
+
+* 出自 `2017-11-05 <https://lore.kernel.org/all/CA+55aFzUvbGjD8nQ-+3oiMBx14c_6zOj2n7KLN3UsJ-qsd4Dcw@mail.gmail.com/>`_::
+
+ And our regression rule has never been "behavior doesn't change".
+ That would mean that we could never make any changes at all.
+
+* 出自 `2020-05-21 <https://lore.kernel.org/all/CAHk-=wiVi7mSrsMP=fLXQrXK_UimybW=ziLOwSzFTtoXUacWVQ@mail.gmail.com/>`_::
+
+ No amount of "you shouldn't have used this" or "that behavior was
+ undefined, it's your own fault your app broke" or "that used to work
+ simply because of a kernel bug" is at all relevant.
+
+* 出自 `2021-05-21 <https://lore.kernel.org/all/CAHk-=wiVi7mSrsMP=fLXQrXK_UimybW=ziLOwSzFTtoXUacWVQ@mail.gmail.com/>`_::
+
+ But no, "that was documented to be broken" (whether it's because the code
+ was in staging or because the man-page said something else) is irrelevant.
+ If staging code is so useful that people end up using it, that means that
+ it's basically regular kernel code with a flag saying "please clean this
+ up".
+
+ [...]
+
+ The other side of the coin is that people who talk about "API stability" are
+ entirely wrong. API's don't matter either. You can make any changes to an
+ API you like - as long as nobody notices.
+
+ Again, the regression rule is not about documentation, not about API's, and
+ not about the phase of the moon.
+
+* 出自 `2012-07-06 <https://lore.kernel.org/all/CA+55aFwnLJ+0sjx92EGREGTWOx84wwKaraSzpTNJwPVV8edw8g@mail.gmail.com/>`_::
+
+ > Now this got me wondering if Debian _unstable_ actually qualifies as a
+ > standard distro userspace.
+
+ Oh, if the kernel breaks some standard user space, that counts. Tons
+ of people run Debian unstable
+
+* 出自 `2011-05-06 <https://lore.kernel.org/all/BANLkTi=KVXjKR82sqsz4gwjr+E0vtqCmvA@mail.gmail.com/>`_::
+
+ It's clearly NOT an internal tracepoint. By definition. It's being
+ used by powertop.
+
+使用者或測試套件／CI 發現的迴歸
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* 出自 `2026-01-22 <https://lore.kernel.org/all/CAHk-=wheQNiW_WtHGO7bKkT7Uib-p+ai2JP9M+z+FYcZ6CAxYA@mail.gmail.com/>`_::
+
+ Users complaining is the only real line in the end.
+
+ [...] a test-suite complaining is then often a *very* good indication that
+ maybe users will hit some problem, and test suite issues should be taken
+ very seriously [...]
+
+ But a test-suite error isn't necessarily where you have to draw the
+ line - it's a big red flag [...]
+
+* 出自 `2024-29-01 <https://lore.kernel.org/all/CAHk-=wg8BrZEzjJ5kUyZzHPZmFqH6ooMN1gRBCofxxCfucgjaw@mail.gmail.com/>`_::
+
+ The "no regressions" rule is not about made-up "if I do this, behavior
+ changes".
+
+ The "no regressions" rule is about *users*.
+
+ If you have an actual user that has been doing insane things, and we
+ change something, and now the insane thing no longer works, at that
+ point it's a regression, and we'll sigh, and go "Users are insane" and
+ have to fix it.
+
+ But if you have some random test that now behaves differently, it's
+ not a regression. It's a *warning* sign, sure: tests are useful.
+
+承認迴歸的發生
+~~~~~~~~~~~~~~
+
+* 出自 `2026-01-22 <https://lore.kernel.org/all/CAHk-=wheQNiW_WtHGO7bKkT7Uib-p+ai2JP9M+z+FYcZ6CAxYA@mail.gmail.com/>`_::
+
+ But starting to argue about users reporting breaking changes is
+ basically the final line for me. I have a couple of people that I have
+ in my spam block-list and refuse to have anything to do with, and they
+ have generally been about exactly that.
+
+ Note how it's not about making mistakes and _causing_ the regression.
+ That's normal. That's development. But then arguing about it is a
+ no-no.
+
+* 出自 `2024-06-23 <https://lore.kernel.org/all/CAHk-=wi_KMO_rJ6OCr8mAWBRg-irziM=T9wxGC+J1VVoQb39gw@mail.gmail.com/>`_::
+
+ We don't introduce regressions and then blame others.
+
+ There's a very clear rule in kernel development: things that break
+ other things ARE NOT FIXES.
+
+ EVER.
+
+ They get reverted, or the thing they broke gets fixed.
+
+* 出自 `2021-06-05 <https://lore.kernel.org/all/CAHk-=wiUVqHN76YUwhkjZzwTdjMMJf_zN4+u7vEJjmEGh3recw@mail.gmail.com/>`_::
+
+ THERE ARE NO VALID ARGUMENTS FOR REGRESSIONS.
+
+ Honestly, security people need to understand that "not working" is not
+ a success case of security. It's a failure case.
+
+ Yes, "not working" may be secure. But security in that case is *pointless*.
+
+* 出自 `2017-10-26(5) <https://lore.kernel.org/lkml/CA+55aFwiiQYJ+YoLKCXjN_beDVfu38mg=Ggg5LFOcqHE8Qi7Zw@mail.gmail.com/>`_::
+
+ [...] when regressions *do* occur, we admit to them and fix them, instead of
+ blaming user space.
+
+ The fact that you have apparently been denying the regression now for
+ three weeks means that I will revert, and I will stop pulling apparmor
+ requests until the people involved understand how kernel development
+ is done.
+
+反覆來回
+~~~~~~~~
+
+* 出自 `2024-05-28 <https://lore.kernel.org/all/CAHk-=wgtb7y-bEh7tPDvDWru7ZKQ8-KMjZ53Tsk37zsPPdwXbA@mail.gmail.com/>`_::
+
+ The "no regressions" rule is that we do not introduce NEW bugs.
+
+ It *literally* came about because we had an endless dance of "fix two
+ bugs, introduce one new one", and that then resulted in a system that
+ you cannot TRUST.
+
+* 出自 `2021-09-20(1) <https://lore.kernel.org/all/CAHk-=wi7DB2SJ-wngVvsJ7Ak2cM556Q8437sOXo4EJt2BWPdEg@mail.gmail.com/>`_::
+
+ And the thing that makes regressions special is that back when I
+ wasn't so strict about these things, we'd end up in endless "seesaw
+ situations" where somebody would fix something, it would break
+ something else, then that something else would break, and it would
+ never actually converge on anything reliable at all.
+
+* 出自 `2015-08-13 <https://lore.kernel.org/all/CA+55aFxk8-BsiKwr_S-c+4G6wihKPQVMLE34H9wOZpeua6W9+Q@mail.gmail.com/>`_::
+
+ The strict policy of no regressions actually originally started mainly wrt
+ suspend/resume issues, where the "fix one machine, break another" kind of
+ back-and-forth caused endless problems, and meant that we didn't actually
+ necessarily make any forward progress, just moving a problem around.
+
+有造成迴歸風險的變更
+~~~~~~~~~~~~~~~~~~~~
+
+* 出自 `2023-06-02 <https://lore.kernel.org/all/CAHk-=wgyAGUMHmQM-5Eb556z5xiHZB7cF05qjrtUH4F7P-1rSA@mail.gmail.com/>`_::
+
+ So what I think you should do is to fix the bug right, with a clean
+ patch, and no crazy hacks. That is something we can then apply and
+ test. All the while knowing full well that "uhhuh, this is a visible
+ change, we may have to revert it".
+
+ If then some *real* load ends up showing a regression, we may just be
+ screwed. Our current behavior may be buggy, but we have the rule that
+ once user space depends on kernel bugs, they become features pretty
+ much by definition, however much we might dislike it.
+
+以核心內的權宜做法避免迴歸
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* 出自 `2017-10-26(6) <https://lore.kernel.org/lkml/CA+55aFxW7NMAMvYhkvz1UPbUTUJewRt6Yb51QAx5RtrWOwjebg@mail.gmail.com/>`_::
+
+ Behavioral changes happen, and maybe we don't even support some
+ feature any more. There's a number of fields in /proc/<pid>/stat that
+ are printed out as zeroes, simply because they don't even *exist* in
+ the kernel any more, or because showing them was a mistake (typically
+ an information leak). But the numbers got replaced by zeroes, so that
+ the code that used to parse the fields still works. The user might not
+ see everything they used to see, and so behavior is clearly different,
+ but things still _work_, even if they might no longer show sensitive
+ (or no longer relevant) information.
+
+缺陷修正造成的迴歸
+~~~~~~~~~~~~~~~~~~
+
+* 出自 `2018-08-03 <https://lore.kernel.org/all/CA+55aFwWZX=CXmWDTkDGb36kf12XmTehmQjbiMPCqCRG2hi9kw@mail.gmail.com/>`_::
+
+ > Kernel had a bug which has been fixed
+
+ That is *ENTIRELY* immaterial.
+
+ Guys, whether something was buggy or not DOES NOT MATTER.
+
+ [...]
+
+ It's basically saying "I took something that worked, and I broke it,
+ but now it's better". Do you not see how f*cking insane that statement
+ is?
+
+內部 API 的變更
+~~~~~~~~~~~~~~~
+
+* 出自 `2017-10-26(7) <https://lore.kernel.org/lkml/CA+55aFxW7NMAMvYhkvz1UPbUTUJewRt6Yb51QAx5RtrWOwjebg@mail.gmail.com/>`_::
+
+ We do API breakage _inside_ the kernel all the time. We will fix
+ internal problems by saying "you now need to do XYZ", but then it's
+ about internal kernel API's, and the people who do that then also
+ obviously have to fix up all the in-kernel users of that API. Nobody
+ can say "I now broke the API you used, and now _you_ need to fix it
+ up". Whoever broke something gets to fix it too.
+
+很久之後才發現的迴歸
+~~~~~~~~~~~~~~~~~~~~
+
+* 出自 `2024-03-28 <https://lore.kernel.org/all/CAHk-=wgFuoHpMk_Z_R3qMXVDgq0N1592+bABkyGjwwSL4zBtHA@mail.gmail.com/>`_::
+
+ I'm definitely not reverting a patch from almost a decade ago as a
+ regression.
+
+ If it took that long to find, it can't be that critical of a regression.
+
+ So yes, let's treat it as a regular bug.
+
+在 linux-next 中測試迴歸修正
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* 在 `2024 年維護者高峰會 <https://lwn.net/Articles/990599/>`_ 上::
+
+ So running fixes though linux-next is just a waste of time.
+
+與迴歸相關的其他幾個面向
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+* 出自 `2025-07-29(2) <https://lore.kernel.org/all/CAHk-=wjj9DvOZtmTkoLtyfHmy5mNKy6q_96d9=4FUEDXre=cww@mail.gmail.com/>`_
+ [這件事 `雖然不完全算是迴歸，但造成了極大的不便 <https://lore.kernel.org/all/CAHk-=wgO0Rx2LcYT4f75Xs46orbJ4JxO2jbAFQnVKDYAjV5HeQ@mail.gmail.com/>`_]::
+
+ I no longer have sound.
+
+ I also suspect that it's purely because "make oldconfig" doesn't work,
+ and probably turned off my old Intel HDA settings. Or something.
+
+ Renaming config parameters is *bad*. I've harped on the Kconfig phase
+ of the kernel build probably being our nastiest point, and a real pain
+ point to people getting involved with development simply because
+ building your own kernel can be so daunting with hundreds of fairly
+ esoteric questions.
+
+..
+ end-of-content
+..
+ 如本文件開頭所述，本文以 GPL-2.0+ 或 CC-BY-4.0 授權提供。如果你想只以
+ CC-BY-4.0 授權散布本文，請以「The Linux kernel developers」作為作者署名，
+ 並連結以下網址作為來源：
+ https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/handling-regressions.rst
+..
+ 注意：只有在 Linux 核心原始碼中找到的本 RST 檔案內容才以 CC-BY-4.0 授權
+ 提供，因為經過處理的文字版本（例如經由核心的建置系統處理）可能包含取自
+ 授權較嚴格之檔案的內容。
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index 90c33d020d34..e73d78362315 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -89,13 +89,13 @@ TODOList:
:maxdepth: 1
debugging/index
+ handling-regressions
security-bugs
cve
embargoed-hardware-issues
TODOList:
-* handling-regressions
* threat-model
維護者資訊
--
2.43.0
^ permalink raw reply [flat|nested] 14+ messages in thread* [PATCH 07/13] docs/zh_TW: process: add deprecated.rst translation
2026-11-06 11:35 [PATCH 00/13] docs/zh_TW: process: add translations of 13 documents Chen-Yu Yeh
` (5 preceding siblings ...)
2026-11-06 11:35 ` [PATCH 06/13] docs/zh_TW: process: add handling-regressions.rst translation Chen-Yu Yeh
@ 2026-11-06 11:35 ` Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 08/13] docs/zh_TW: process: add kernel-docs.rst translation Chen-Yu Yeh
` (5 subsequent siblings)
12 siblings, 0 replies; 14+ messages in thread
From: Chen-Yu Yeh @ 2026-11-06 11:35 UTC (permalink / raw)
To: Alex Shi, Jonathan Corbet
Cc: Weijie Yuan, Dongliang Mu, Yanteng Si, linux-doc, linux-kernel,
Chen-Yu Yeh
Translate Documentation/process/deprecated.rst into Traditional Chinese
from the current English text, including the kmalloc_obj() family
section and the rewritten strncpy() section that lists its
replacements. There is no zh_CN translation of this file to consult.
The note in the allocator section links to the "Zero-length and
one-element arrays" section by its HTML anchor; since the translated
heading no longer produces that anchor, add an explicit
zero-length-and-one-element-arrays target before the section.
List the new file in the toctree of process/index.rst, under "Other
material" as in the English index, and drop it from the TODOList.
update to commit 079a028d6327 ("string: Remove strncpy() from the
kernel")
Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
.../translations/zh_TW/process/deprecated.rst | 363 ++++++++++++++++++
.../translations/zh_TW/process/index.rst | 6 +-
2 files changed, 368 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_TW/process/deprecated.rst
diff --git a/Documentation/translations/zh_TW/process/deprecated.rst b/Documentation/translations/zh_TW/process/deprecated.rst
new file mode 100644
index 000000000000..7a5e42a12041
--- /dev/null
+++ b/Documentation/translations/zh_TW/process/deprecated.rst
@@ -0,0 +1,363 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_TW.rst
+
+:Original: Documentation/process/deprecated.rst
+
+.. _tw_deprecated:
+
+======================================
+已棄用的介面、語言特性、屬性與慣例
+======================================
+
+在理想的世界裡，我們可以在單一開發週期內，把某個已棄用 API 的所有使用處
+都轉換成新的 API，並完全移除舊的 API。然而，由於核心的規模、維護者的層級
+架構以及時程等因素，這類轉換並不總是能一次完成。這表示在移除舊用法的同時，
+新的用法可能會偷偷混進核心，只會讓移除該 API 的工作量越來越大。為了讓開發者
+了解哪些東西已被棄用以及原因，我們建立了這份清單；當有人提議把已棄用的東西
+納入核心時，可以引用這份清單。
+
+__deprecated
+------------
+雖然這個屬性確實會在視覺上把介面標示為已棄用，但它 `在建置時已不再產生警告
+<https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_，
+因為核心的長期目標之一是在建置時不產生任何警告，而且實際上也沒有人在著手
+移除這些已棄用的介面。雖然在標頭檔中使用 `__deprecated` 來標註舊的 API
+是不錯的做法，但這並不是完整的解決方案。這類介面必須從核心中完全移除，
+或者加入這份檔案，以勸阻其他人未來再使用它們。
+
+BUG() 和 BUG_ON()
+-----------------
+請改用 WARN() 和 WARN_ON()，並盡可能妥善地處理這種「不可能發生」的錯誤
+狀況。雖然 BUG() 系列 API 最初是設計成「不可能發生的情況」的斷言，並「安全
+地」終止核心執行緒，但事實證明它們的風險實在太高。（例如：「鎖需要以什麼
+順序釋放？各種狀態都已經恢復了嗎？」）使用 BUG() 經常會讓系統變得不穩定或
+完全崩潰，使得除錯甚至取得可用的當機報告都變得不可能。Linus 對此有 `非常強烈
+<https://lore.kernel.org/lkml/CA+55aFy6jNLsywVYdGp83AMrXBo_P-pkjkphPGrO=82SPKCpLQ@mail.gmail.com/>`_
+的 `看法
+<https://lore.kernel.org/lkml/CAHk-=whDHsbK3HTOpTF=ue_o04onRwTEaK_ZoJp_fjbqq4+=Jw@mail.gmail.com/>`_。
+
+請注意，WARN() 系列只應該用於「預期不會執行到」的情況。如果要對「可能執行
+到但不希望發生」的情況發出警告，請使用 pr_warn() 系列函式。系統擁有者可能
+設定了 *panic_on_warn* sysctl，以確保系統在遇到「不可能執行到」的狀況時不會
+繼續執行。（例如，請參考 `這個
+<https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_
+之類的 commit。）
+
+在配置函式的參數中直接進行算術運算
+----------------------------------
+動態的大小計算（尤其是乘法）不應該在記憶體配置函式（或類似函式）的參數中
+進行，因為有溢位的風險。這可能導致數值繞回（wrap around），使實際配置的
+空間比呼叫者預期的還小。使用這些配置出來的空間，可能導致堆積（heap）記憶體
+的線性溢位以及其他異常行為。（一個例外是字面常數值，此時編譯器可以在可能
+溢位時發出警告。不過在這些情況下，比較好的做法仍然是依照下面的建議重構程式
+碼，以避免直接進行算術運算。）
+
+例如，不要像這樣使用 ``count * size`` 作為參數::
+
+ foo = kmalloc(count * size, GFP_KERNEL);
+
+而應該使用配置函式的雙因子形式::
+
+ foo = kmalloc_array(count, size, GFP_KERNEL);
+
+具體來說，kmalloc() 可以換成 kmalloc_array()，kzalloc() 可以換成
+kcalloc()。
+
+如果沒有可用的雙因子形式，就應該使用溢位時會飽和（saturate-on-overflow）的
+輔助函式::
+
+ bar = dma_alloc_coherent(dev, array_size(count, size), &dma, GFP_KERNEL);
+
+另一個應避免的常見情況，是計算尾端帶有其他結構陣列的結構大小，例如::
+
+ header = kzalloc(sizeof(*header) + count * sizeof(*header->item),
+ GFP_KERNEL);
+
+請改用輔助函式::
+
+ header = kzalloc(struct_size(header, item, count), GFP_KERNEL);
+
+.. note:: 如果你在尾端陣列成員為零長度陣列或單元素陣列的結構上使用
+ struct_size()，請重構這類陣列的用法，改用 `彈性陣列成員
+ <#zero-length-and-one-element-arrays>`_。
+
+其他計算請組合使用 size_mul()、size_add() 和 size_sub() 輔助函式。例如
+以下這種情況::
+
+ foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL);
+
+請改用輔助函式::
+
+ foo = krealloc(size_add(current_size,
+ size_mul(chunk_size,
+ size_sub(count, 3))), GFP_KERNEL);
+
+更多細節請參考 array3_size() 和 flex_array_size()，以及相關的
+check_mul_overflow()、check_add_overflow()、check_sub_overflow() 和
+check_shl_overflow() 系列函式。
+
+simple_strtol()、simple_strtoll()、simple_strtoul()、simple_strtoull()
+----------------------------------------------------------------------
+simple_strtol()、simple_strtoll()、simple_strtoul() 和 simple_strtoull()
+函式會刻意忽略溢位，這可能讓呼叫者得到預期之外的結果。對應的 kstrtol()、
+kstrtoll()、kstrtoul() 和 kstrtoull() 函式通常是正確的替代品，但請注意，
+它們要求字串必須以 NUL 或換行字元結尾。
+
+strcpy()
+--------
+strcpy() 不會對目的緩衝區做任何邊界檢查。這可能導致超出緩衝區結尾的線性溢位，
+進而造成各種異常行為。雖然 `CONFIG_FORTIFY_SOURCE=y` 和各種編譯器旗標有助於
+降低使用這個函式的風險，但沒有任何好理由再新增這個函式的用法。安全的替代品
+是 strscpy()，但凡是用到 strcpy() 回傳值的地方都必須小心處理，因為 strscpy()
+回傳的不是指向目的緩衝區的指標，而是複製的非 NUL 位元組數（截斷時則回傳負的
+errno）。
+
+strncpy()
+---------
+strncpy() 已經從核心中移除。所有原本的呼叫者都已改用更安全的替代函式。
+
+strncpy() 不保證目的緩衝區會以 NUL 結尾，因而導致線性讀取溢位和其他異常行為。
+它也會無條件地以 NUL 填補目的緩衝區，對只使用以 NUL 結尾字串的呼叫者來說，
+這是不必要的效能損失。由於它具有多種不同的行為，從這個 API 很難判斷作者進行
+複製時的真正意圖。
+
+strncpy() 的替代函式如下：
+
+- strscpy()：目的緩衝區必須以 NUL 結尾時使用。
+- strscpy_pad()：目的緩衝區必須以 NUL 結尾並以零填補時使用（例如跨越權限
+ 邊界的結構）。
+- memtostr()：來源是不以 NUL 結尾的固定寬度資料、目的緩衝區需以 NUL 結尾時
+ 使用（來源需加上 `__nonstring` 屬性）。
+- memtostr_pad()：同上，但另外以零填補。
+- strtomem()：目的是不以 NUL 結尾的固定寬度緩衝區時使用，目的緩衝區需加上
+ `__nonstring` 屬性。
+- strtomem_pad()：目的緩衝區不以 NUL 結尾且也需要以零填補時使用。
+- memcpy_and_pad()：從可能沒有結尾字元的來源進行有界複製，且目的緩衝區大小
+ 是執行期數值時使用。
+
+strlcpy()
+---------
+strlcpy() 會先讀取整個來源緩衝區（因為它的回傳值應該與 strlen() 的回傳值
+相同）。這次讀取可能會超出目的緩衝區的大小限制。這既沒有效率，而且當來源
+字串不以 NUL 結尾時，還可能導致線性讀取溢位。安全的替代品是 strscpy()，但
+凡是用到 strlcpy() 回傳值的地方都必須小心處理，因為 strscpy() 在截斷時會
+回傳負的 errno 值。
+
+%p 格式指定符
+-------------
+傳統上，在格式字串中使用 "%p" 經常會造成位址在 dmesg、proc、sysfs 等處外洩
+的漏洞。為了避免這些漏洞被利用，核心中所有 "%p" 的用法現在都會印出雜湊值，
+使其無法用於定址。不應該在核心中新增 "%p" 的用法。對於程式碼（text）位址，
+使用 "%pS" 可能比較好，因為它會改為印出更有用的符號名稱。至於幾乎其他所有
+情況，就乾脆不要加入 "%p"。
+
+轉述 Linus 目前的 `指導原則 <https://lore.kernel.org/lkml/CA+55aFwQEd_d40g4mUCSsVRZzrFPUJt74vc6PPpb675hYNXcKw@mail.gmail.com/>`_：
+
+- 如果雜湊過的 "%p" 值沒有意義，請先問問自己指標本身是否重要。也許應該把它
+ 整個移除？
+- 如果你真的認為真實的指標值很重要，那麼為什麼某些系統狀態或使用者權限等級
+ 會被視為「特殊」？如果你認為自己能（在註解和 commit 日誌中）提出足以經得起
+ Linus 檢驗的理由，也許可以使用 "%px"，同時確保權限設定合理。
+
+如果你在除錯時遇到 "%p" 雜湊造成的問題，可以暫時以除錯旗標
+"`no_hash_pointers
+<https://git.kernel.org/linus/5ead723a20e0447bc7db33dc3070b420e5f80aa6>`_"
+開機。
+
+可變長度陣列（VLA）
+-------------------
+使用堆疊上的 VLA 所產生的機器碼，比靜態大小的堆疊陣列差得多。雖然這些不容
+忽視的 `效能問題 <https://git.kernel.org/linus/02361bc77888>`_ 已足以成為
+消除 VLA 的理由，但它們同時也是安全風險。堆疊陣列的動態成長可能超出堆疊區段
+中剩餘的記憶體。這可能導致當機，可能覆寫堆疊尾端的敏感內容（在沒有啟用
+`CONFIG_THREAD_INFO_IN_TASK=y` 建置時），或覆寫與堆疊相鄰的記憶體（在沒有
+啟用 `CONFIG_VMAP_STACK=y` 建置時）。
+
+隱式的 switch case 貫穿（fall-through）
+---------------------------------------
+C 語言允許在某個 case 結尾缺少 "break" 敘述時，貫穿到下一個 case。然而這會
+讓程式碼產生歧義，因為缺少 break 究竟是刻意的還是 bug，並不總是那麼清楚。
+例如，光看程式碼並無法明顯看出 `STATE_ONE` 是否刻意設計成貫穿到
+`STATE_TWO`::
+
+ switch (value) {
+ case STATE_ONE:
+ do_something();
+ case STATE_TWO:
+ do_other();
+ break;
+ default:
+ WARN("unknown state");
+ }
+
+由於已經出現過一長串 `因缺少 "break" 敘述而造成的缺陷
+<https://cwe.mitre.org/data/definitions/484.html>`_，我們不再允許隱式貫穿。
+為了標示刻意的貫穿情況，我們採用了一個名為 "fallthrough" 的偽關鍵字巨集，
+它會展開成 gcc 的擴充語法 `__attribute__((__fallthrough__))
+<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_。
+（等到 C17/C18 的 `[[fallthrough]]` 語法普遍獲得 C 編譯器、靜態分析器和
+IDE 支援時，我們就可以改用該語法來實作這個巨集偽關鍵字。）
+
+所有 switch/case 區塊都必須以下列其中之一結尾：
+
+* break;
+* fallthrough;
+* continue;
+* goto <label>;
+* return [expression];
+
+.. _zero-length-and-one-element-arrays:
+
+零長度與單元素陣列
+------------------
+核心中經常需要一種方式，來宣告結構尾端帶有一組大小動態決定的元素。在這些
+情況下，核心程式碼應該一律使用 `「彈性陣列成員」（flexible array members）
+<https://en.wikipedia.org/wiki/Flexible_array_member>`_。不應該再使用舊式的
+單元素或零長度陣列。
+
+在較舊的 C 程式碼中，大小動態決定的尾端元素是透過在結構結尾宣告一個單元素
+陣列來實作的::
+
+ struct something {
+ size_t count;
+ struct foo items[1];
+ };
+
+這導致透過 sizeof() 計算大小時很容易出錯（必須扣掉那一個尾端元素的大小，
+才能得到「標頭」的正確大小）。為了避免這類大小問題，後來引入了一個
+`GNU C 擴充 <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_，
+允許使用零長度陣列::
+
+ struct something {
+ size_t count;
+ struct foo items[0];
+ };
+
+但這又導致了其他問題，而且並未解決兩種寫法共有的一些問題，例如無法偵測到
+這種陣列被意外地 _沒有_ 放在結構的結尾（這可能直接發生，也可能在這種結構
+位於 union、結構中的結構等情況下發生）。
+
+C99 引入了「彈性陣列成員」，它的陣列宣告完全不帶數字大小::
+
+ struct something {
+ size_t count;
+ struct foo items[];
+ };
+
+這就是核心預期宣告大小動態決定的尾端元素的方式。它讓編譯器能在彈性陣列不是
+結構中最後一個成員時產生錯誤，有助於防止某些 `未定義行為
+<https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_
+的缺陷被不小心引入程式碼庫。它也讓編譯器能正確分析陣列大小（透過 sizeof()、
+`CONFIG_FORTIFY_SOURCE` 和 `CONFIG_UBSAN_BOUNDS`）。舉例來說，沒有任何機制
+會警告我們，以下對零長度陣列套用 sizeof() 運算子的結果永遠是零::
+
+ struct something {
+ size_t count;
+ struct foo items[0];
+ };
+
+ struct something *instance;
+
+ instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
+ instance->count = count;
+
+ size = sizeof(instance->items) * instance->count;
+ memcpy(instance->items, source, size);
+
+在上面程式碼的最後一行，``size`` 的值結果是 ``zero``，但有人可能以為它代表
+剛剛為尾端陣列 ``items`` 配置的動態記憶體的總位元組數。以下是這個問題的幾個
+例子：`連結 1
+<https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_、
+`連結 2
+<https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_。
+相對地，`彈性陣列成員屬於不完整型別，因此不能套用 sizeof() 運算子
+<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_，所以任何對這類運算子
+的誤用都會在建置時立刻被發現。
+
+至於單元素陣列，必須特別留意 `這種陣列佔用的空間至少與該型別的單一物件相同
+<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_，
+因此它們會計入外層結構的大小。每當有人要為含有這種陣列成員的結構計算需要
+配置的動態記憶體總大小時，就很容易出錯::
+
+ struct something {
+ size_t count;
+ struct foo items[1];
+ };
+
+ struct something *instance;
+
+ instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL);
+ instance->count = count;
+
+ size = sizeof(instance->items) * instance->count;
+ memcpy(instance->items, source, size);
+
+在上面的例子中，使用 struct_size() 輔助函式時必須記得計算 ``count - 1``，
+否則就會——不小心地——多配置一個 ``items`` 物件的記憶體。最乾淨、最不容易
+出錯的實作方式，是使用 `彈性陣列成員`，並搭配 struct_size() 和
+flex_array_size() 輔助函式::
+
+ struct something {
+ size_t count;
+ struct foo items[];
+ };
+
+ struct something *instance;
+
+ instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
+ instance->count = count;
+
+ memcpy(instance->items, source, flex_array_size(instance, items, instance->count));
+
+有兩種特殊的替換情況必須使用 DECLARE_FLEX_ARRAY() 輔助巨集。（請注意，在
+UAPI 標頭檔中使用時，它的名稱是 __DECLARE_FLEX_ARRAY()。）這兩種情況是：
+彈性陣列單獨存在於結構中，或是 union 的一部分。C99 規格不允許這兩種用法，
+但並沒有技術上的理由（從這類陣列在這些地方的既有用法，以及
+DECLARE_FLEX_ARRAY() 所用的變通方法都可以看出來）。例如，要轉換以下程式碼::
+
+ struct something {
+ ...
+ union {
+ struct type1 one[0];
+ struct type2 two[0];
+ };
+ };
+
+就必須使用這個輔助巨集::
+
+ struct something {
+ ...
+ union {
+ DECLARE_FLEX_ARRAY(struct type1, one);
+ DECLARE_FLEX_ARRAY(struct type2, two);
+ };
+ };
+
+直接撰寫的結構物件 kmalloc 指派
+-------------------------------
+直接撰寫 kmalloc() 系列的配置指派，會讓核心（以及編譯器）無法檢查被指派
+變數的型別，因而限制了相關的自我檢查（introspection），而這些檢查原本可能
+有助於對齊、繞回（wrap-around）或額外的強化措施。kmalloc_obj() 系列巨集
+提供了這種自我檢查，可用於單一物件、陣列和彈性物件配置的常見程式碼模式。
+例如，下列直接撰寫的指派::
+
+ ptr = kmalloc(sizeof(*ptr), gfp);
+ ptr = kzalloc(sizeof(*ptr), gfp);
+ ptr = kmalloc_array(count, sizeof(*ptr), gfp);
+ ptr = kcalloc(count, sizeof(*ptr), gfp);
+ ptr = kmalloc(struct_size(ptr, flex_member, count), gfp);
+ ptr = kmalloc(sizeof(struct foo), gfp);
+
+分別改寫成::
+
+ ptr = kmalloc_obj(*ptr [, gfp] );
+ ptr = kzalloc_obj(*ptr [, gfp] );
+ ptr = kmalloc_objs(*ptr, count [, gfp] );
+ ptr = kzalloc_objs(*ptr, count [, gfp] );
+ ptr = kmalloc_flex(*ptr, flex_member, count [, gfp] );
+ __auto_type ptr = kmalloc_obj(struct foo [, gfp] );
+
+gfp 參數是可選的，預設值為 GFP_KERNEL。如果 `ptr->flex_member` 有以
+__counted_by() 標註，那麼當 `count` 大於與 `flex_member` 相關聯的計數器
+成員所能儲存的最大值時，配置就會自動失敗。
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index e73d78362315..d7d947d33cf5 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -113,10 +113,14 @@ TODOList:
這裡是一些大多數開發者會感興趣的其他社群指南：
+.. toctree::
+ :maxdepth: 1
+
+ deprecated
+
TODOList:
* kernel-docs
-* deprecated
.. only:: subproject and html
--
2.43.0
^ permalink raw reply [flat|nested] 14+ messages in thread* [PATCH 08/13] docs/zh_TW: process: add kernel-docs.rst translation
2026-11-06 11:35 [PATCH 00/13] docs/zh_TW: process: add translations of 13 documents Chen-Yu Yeh
` (6 preceding siblings ...)
2026-11-06 11:35 ` [PATCH 07/13] docs/zh_TW: process: add deprecated.rst translation Chen-Yu Yeh
@ 2026-11-06 11:35 ` Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 09/13] docs/zh_TW: process: add maintainer-handbooks.rst translation Chen-Yu Yeh
` (4 subsequent siblings)
12 siblings, 0 replies; 14+ messages in thread
From: Chen-Yu Yeh @ 2026-11-06 11:35 UTC (permalink / raw)
To: Alex Shi, Jonathan Corbet
Cc: Weijie Yuan, Dongliang Mu, Yanteng Si, linux-doc, linux-kernel,
Chen-Yu Yeh
Translate Documentation/process/kernel-docs.rst into Traditional
Chinese from the current English text, including the Rust section and
The Linux Memory Manager entry. Book, site and talk titles are kept
in English, and the long book titles are wrapped to fit in 80 columns.
There is no zh_CN translation of this file to consult.
List the new file in the toctree of process/index.rst, before
deprecated as in the English index, and drop it from the TODOList.
update to commit 57937eac1f78 ("kernel-docs: Add book to
process/kernel-docs.rst")
Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
.../translations/zh_TW/process/index.rst | 5 +-
.../zh_TW/process/kernel-docs.rst | 355 ++++++++++++++++++
2 files changed, 356 insertions(+), 4 deletions(-)
create mode 100644 Documentation/translations/zh_TW/process/kernel-docs.rst
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index d7d947d33cf5..8c558bbf30e4 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -116,12 +116,9 @@ TODOList:
.. toctree::
:maxdepth: 1
+ kernel-docs
deprecated
-TODOList:
-
-* kernel-docs
-
.. only:: subproject and html
目錄
diff --git a/Documentation/translations/zh_TW/process/kernel-docs.rst b/Documentation/translations/zh_TW/process/kernel-docs.rst
new file mode 100644
index 000000000000..633a08f30c44
--- /dev/null
+++ b/Documentation/translations/zh_TW/process/kernel-docs.rst
@@ -0,0 +1,355 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_TW.rst
+
+:Original: Documentation/process/kernel-docs.rst
+
+.. _tw_kernel_docs:
+
+其他核心文件索引
+================
+
+之所以需要這樣一份文件，是因為在 linux-kernel 郵件列表上，同樣的問題、
+同樣詢問資料出處的請求一再出現。
+
+幸運的是，隨著越來越多人接觸 GNU/Linux，也有越來越多人對核心產生興趣。
+但光是閱讀原始程式碼並不總是足夠。看懂程式碼很容易，卻可能錯過這些
+程式碼背後的概念、理念和設計決策。
+
+不幸的是，可供初學者入門的文件並不多。而且即使有，也沒有一個「眾所周知」
+的地方來收錄它們。這份文件試圖彌補這個缺口。
+
+如果你知道任何這裡沒有列出的文章，或者寫了新的文件，請務必依照核心的
+修補程式提交流程，在這裡加上它的參考資料。也歡迎任何更正、想法或意見。
+
+所有文件都以下列欄位編目：文件的「標題」、「作者」、可以找到該文件的
+「URL」、有助於搜尋特定主題的一些「關鍵字」，以及文件的簡短「說明」。
+
+.. note::
+
+ 本文件各節中的文件依出版日期排序，由新到舊。維護者應定期淘汰已經
+ 過時或不再適用的資源；但基礎書籍除外。
+
+Linux 核心原始程式碼樹中的文件
+------------------------------
+
+Sphinx 書籍應以 ``make {htmldocs | pdfdocs | epubdocs}`` 建置。
+
+ * 名稱：**linux/Documentation**
+
+ :作者: 許多人。
+ :位置: Documentation/
+ :關鍵字: 文字檔、Sphinx。
+ :說明: 隨核心原始程式碼一起提供、位於 Documentation 目錄中的
+ 文件。本文件中的一些頁面（包括本文件本身）已經移到那裡，可能比
+ 網頁版本更新。
+
+線上文件
+--------
+
+ * 標題：**Linux Kernel Mailing List Glossary**
+
+ :作者: 多人
+ :URL: https://kernelnewbies.org/KernelGlossary
+ :日期: 持續更新的版本
+ :關鍵字: 詞彙表、術語、linux-kernel。
+ :說明: 引言中寫道：「這份詞彙表旨在簡要說明你在討論 Linux 核心時
+ 可能會聽到的一些縮寫和術語」。
+
+ * 標題：**The Linux Kernel Module Programming Guide**
+
+ :作者: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram,
+ Jim Huang.
+ :URL: https://sysprog21.github.io/lkmpg/
+ :日期: 2021
+ :關鍵字: 模組、GPL 書籍、/proc、ioctl、系統呼叫、中斷處理常式。
+ :說明: 一本非常好的 GPL 書籍，主題是模組程式設計，附有大量範例。
+ 新版本目前在 https://github.com/sysprog21/lkmpg 積極維護中。
+
+已出版的書籍
+------------
+
+ * 標題：**The Linux Memory Manager**
+
+ :作者: Lorenzo Stoakes
+ :出版社: No Starch Press
+ :日期: 2025 年 2 月
+ :頁數: 1300
+ :ISBN: 978-1718504462
+ :備註: 記憶體管理。完整草稿可透過預購搶先閱讀，正式版預計於
+ 2025 年秋季發行。詳情請見
+ https://nostarch.com/linux-memory-manager 。
+
+ * 標題：**Practical Linux System Administration: A Guide to Installation,
+ Configuration, and Management, 1st Edition**
+
+ :作者: Kenneth Hess
+ :出版社: O'Reilly Media
+ :日期: 2023 年 5 月
+ :頁數: 246
+ :ISBN: 978-1098109035
+ :備註: 系統管理
+
+ * 標題：**Linux Kernel Debugging: Leverage proven tools and advanced
+ techniques to effectively debug Linux kernels and kernel modules**
+
+ :作者: Kaiwan N Billimoria
+ :出版社: Packt Publishing Ltd
+ :日期: 2022 年 8 月
+ :頁數: 638
+ :ISBN: 978-1801075039
+ :備註: 除錯書籍
+
+ * 標題：**Linux Kernel Programming: A Comprehensive Guide to Kernel
+ Internals, Writing Kernel Modules, and Kernel Synchronization**
+
+ :作者: Kaiwan N Billimoria
+ :出版社: Packt Publishing Ltd
+ :日期: 2021 年 3 月（第二版於 2024 年出版）
+ :頁數: 754
+ :ISBN: 978-1789953435（第二版 ISBN 為 978-1803232225）
+
+ * 標題：**Linux Kernel Programming Part 2 - Char Device Drivers and
+ Kernel Synchronization: Create user-kernel interfaces, work with
+ peripheral I/O, and handle hardware interrupts**
+
+ :作者: Kaiwan N Billimoria
+ :出版社: Packt Publishing Ltd
+ :日期: 2021 年 3 月
+ :頁數: 452
+ :ISBN: 978-1801079518
+
+ * 標題：**Linux System Programming: Talking Directly to the Kernel and C
+ Library**
+
+ :作者: Robert Love
+ :出版社: O'Reilly Media
+ :日期: 2013 年 6 月
+ :頁數: 456
+ :ISBN: 978-1449339531
+ :備註: 基礎書籍
+
+ * 標題：**Linux Kernel Development, 3rd Edition**
+
+ :作者: Robert Love
+ :出版社: Addison-Wesley
+ :日期: 2010 年 7 月
+ :頁數: 440
+ :ISBN: 978-0672329463
+ :備註: 基礎書籍
+
+.. _tw_ldd3_published:
+
+ * 標題：**Linux Device Drivers, 3rd Edition**
+
+ :作者: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman
+ :出版社: O'Reilly & Associates
+ :日期: 2005
+ :頁數: 636
+ :ISBN: 0-596-00590-3
+ :備註: 基礎書籍。更多資訊請見
+ http://www.oreilly.com/catalog/linuxdrive3/
+ PDF 格式的 URL：https://lwn.net/Kernel/LDD3/
+
+ * 標題：**The Design of the UNIX Operating System**
+
+ :作者: Maurice J. Bach
+ :出版社: Prentice Hall
+ :日期: 1986
+ :頁數: 471
+ :ISBN: 0-13-201757-1
+ :備註: 基礎書籍
+
+其他
+----
+
+ * 名稱：**Cross-Referencing Linux**
+
+ :URL: https://elixir.bootlin.com/
+ :關鍵字: 瀏覽原始程式碼。
+ :說明: 另一個網頁版的 Linux 核心原始程式碼瀏覽器。提供大量變數與
+ 函式的交叉參照，可以看到它們在哪裡定義、在哪裡使用。
+
+ * 名稱：**Linux Weekly News**
+
+ :URL: https://lwn.net
+ :關鍵字: 最新核心新聞。
+ :說明: 標題已經說明了一切。其中有固定的核心專欄，彙整每週開發者的
+ 工作、錯誤修正、新功能以及推出的版本。
+
+ * 名稱：**The home page of Linux-MM**
+
+ :作者: Linux-MM 團隊。
+ :URL: https://linux-mm.org/
+ :關鍵字: 記憶體管理、Linux-MM、mm 修補程式、TODO、文件、郵件列表。
+ :說明: 專門介紹 Linux 記憶體管理開發的網站。有記憶體相關的修補程式、
+ HOWTO、連結、mm 開發者……如果你對記憶體管理開發有興趣，千萬別
+ 錯過！
+
+ * 名稱：**Kernel Newbies IRC Channel and Website**
+
+ :URL: https://www.kernelnewbies.org
+ :關鍵字: IRC、新手、頻道、提問。
+ :說明: irc.oftc.net 上的 #kernelnewbies。
+ #kernelnewbies 是專為「新手」核心駭客設立的 IRC 網路。參與者
+ 大多是正在學習核心的人、正在進行核心專案的人，或是願意幫助較
+ 沒經驗的核心開發者的專業核心駭客。
+ #kernelnewbies 位於 OFTC IRC 網路。
+ 請以 irc.oftc.net 作為伺服器，然後 /join #kernelnewbies。
+ kernelnewbies 網站上也有文章、文件、FAQ……
+
+ * 名稱：**linux-kernel mailing list archives and search engines**
+
+ :URL: https://subspace.kernel.org
+ :URL: https://lore.kernel.org
+ :關鍵字: linux-kernel、封存、搜尋。
+ :說明: 一些 linux-kernel 郵件列表的封存站。如果你知道更好的或
+ 其他的，請告訴我。
+
+ * 名稱：**The Linux Foundation YouTube channel**
+
+ :URL: https://www.youtube.com/user/thelinuxfoundation
+ :關鍵字: linux、影片、linux-foundation、youtube。
+ :說明: Linux 基金會會上傳其協作活動、Linux 研討會（包括 LinuxCon）
+ 的影片，以及其他與 Linux 和軟體開發相關的原創研究與內容。
+
+Rust
+----
+
+ * 標題：**Rust for Linux**
+
+ :作者: 多人
+ :URL: https://rust-for-linux.com/
+ :日期: 持續更新的版本
+ :關鍵字: 詞彙表、術語、linux-kernel、rust。
+ :說明: 網站上寫道：「Rust for Linux 是為 Linux 核心加入 Rust 語言
+ 支援的專案。這個網站旨在彙集與此專案相關的連結、文件和資源」。
+
+ * 標題：**Learn Rust the Dangerous Way**
+
+ :作者: Cliff L. Biffle
+ :URL: https://cliffle.com/p/dangerust/
+ :日期: 2024 年 9 月 11 日存取
+ :關鍵字: rust、部落格。
+ :說明: 網站上寫道：「LRtDW 是一系列文章，為可能沒有正式資訊科學
+ 背景的低階 C 程式設計師，把 Rust 的特性放在實際情境中說明——也就是
+ 從事韌體、遊戲引擎、作業系統核心之類工作的人。基本上，就是像我
+ 這樣的人。」。它逐行示範如何把 C 轉換成 Rust。
+
+ * 標題：**The Rust Book**
+
+ :作者: Steve Klabnik 和 Carol Nichols，以及 Rust 社群的貢獻者
+ :URL: https://doc.rust-lang.org/book/
+ :日期: 2024 年 9 月 11 日存取
+ :關鍵字: rust、書籍。
+ :說明: 網站上寫道：「本書充分發揮 Rust 賦予使用者能力的潛力。這是
+ 一份友善、平易近人的文字，不只要幫助你提升 Rust 知識，也要提升你
+ 身為程式設計師整體的能力範圍與信心。那就一頭栽進來，準備好學習——
+ 歡迎加入 Rust 社群！」。
+
+ * 標題：**Rust for the Polyglot Programmer**
+
+ :作者: Ian Jackson
+ :URL: https://www.chiark.greenend.org.uk/~ianmdlvl/rust-polyglot/index.html
+ :日期: 2022 年 12 月
+ :關鍵字: rust、部落格、工具。
+ :說明: 網站上寫道：「Rust 的指南和入門介紹有很多。這一份有些不同：
+ 它是寫給已經懂得許多其他程式語言的資深程式設計師。我試著寫得夠
+ 全面，可以作為 Rust 任何領域的起點，但除了與你預期不同的地方之外，
+ 盡量不深入細節。此外，這份指南並非完全不帶個人觀點，其中包括對
+ 函式庫（crate）、工具等的推薦。」。
+
+ * 標題：**Fasterthanli.me**
+
+ :作者: Amos Wenger
+ :URL: https://fasterthanli.me/
+ :日期: 2024 年 9 月 11 日存取
+ :關鍵字: rust、部落格、新聞。
+ :說明: 網站上寫道：「我製作關於電腦如何運作的文章和影片。我的內容
+ 篇幅很長、具教學性且富探索性——而且常常是教 Rust 的藉口！」。
+
+ * 標題：**Comprehensive Rust**
+
+ :作者: Google 的 Android 團隊
+ :URL: https://google.github.io/comprehensive-rust/
+ :日期: 2024 年 9 月 13 日存取
+ :關鍵字: rust、部落格。
+ :說明: 網站上寫道：「本課程涵蓋 Rust 的全部範圍，從基本語法到泛型
+ 和錯誤處理等進階主題」。
+
+ * 標題：**The Embedded Rust Book**
+
+ :作者: 多位貢獻者，主要是 Jorge Aparicio
+ :URL: https://docs.rust-embedded.org/book/
+ :日期: 2024 年 9 月 13 日存取
+ :關鍵字: rust、部落格。
+ :說明: 網站上寫道：「一本介紹如何在『裸機』嵌入式系統（例如微控制器）
+ 上使用 Rust 程式語言的入門書」。
+
+ * 標題：**Experiment: Improving the Rust Book**
+
+ :作者: Brown University 的 Cognitive Engineering Lab
+ :URL: https://rust-book.cs.brown.edu/
+ :日期: 2024 年 9 月 22 日存取
+ :關鍵字: rust、部落格。
+ :說明: 網站上寫道：「這個實驗的目標是評估並改進 Rust Book 的內容，
+ 幫助大家更有效地學習 Rust。」。
+
+ * 標題：**New Rustacean** （podcast）
+
+ :作者: Chris Krycho
+ :URL: https://newrustacean.com/
+ :日期: 2024 年 9 月 22 日存取
+ :關鍵字: rust、podcast。
+ :說明: 網站上寫道：「這是一個從零開始學習 Rust 程式語言的
+ podcast！除了這個漂亮的登陸頁面之外，網站的所有內容都是用 Rust
+ 自己的文件工具建置的。」。
+
+ * 標題：**Opsem-team** （儲存庫）
+
+ :作者: Operational semantics team
+ :URL: https://github.com/rust-lang/opsem-team/tree/main
+ :日期: 2024 年 9 月 22 日存取
+ :關鍵字: rust、儲存庫。
+ :說明: README 中寫道：「opsem 團隊是 unsafe-code-guidelines 工作
+ 小組的後繼者，負責回答許多關於 unsafe Rust 語意的困難問題」。
+
+ * 標題：**You Can't Spell Trust Without Rust**
+
+ :作者: Alexis Beingessner
+ :URL: https://repository.library.carleton.ca/downloads/1j92g820w?locale=en
+ :日期: 2015
+ :關鍵字: rust、碩士、論文。
+ :說明: 這篇論文聚焦於 Rust 的所有權系統，它透過控制資料的操作與
+ 生命週期來確保記憶體安全；論文也指出了它的限制，並將它與 Cyclone
+ 和 C++ 中的類似系統做比較。
+
+ * 名稱：**Linux Plumbers (LPC) 2024 Rust presentations**
+
+ :講題: Rust microconference
+ :URL: https://lpc.events/event/18/sessions/186/#20240918
+ :講題: Rust for Linux
+ :URL: https://lpc.events/event/18/contributions/1912/
+ :講題: Journey of a C kernel engineer starting a Rust driver project
+ :URL: https://lpc.events/event/18/contributions/1911/
+ :講題: Crafting a Linux kernel scheduler that runs in user-space
+ using Rust
+ :URL: https://lpc.events/event/18/contributions/1723/
+ :講題: openHCL: A Linux and Rust based paravisor
+ :URL: https://lpc.events/event/18/contributions/1956/
+ :關鍵字: rust、lpc、演講。
+ :說明: 一些與 Rust 相關的 LPC 演講。
+
+ * 名稱：**The Rustacean Station Podcast**
+
+ :URL: https://rustacean-station.org/
+ :關鍵字: rust、podcast。
+ :說明: 為 Rust 程式語言製作 podcast 內容的社群專案。
+
+-------
+
+本文件最初基於：
+
+ https://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html
+
+由 Juan-Mariano de Goyeneche 撰寫
--
2.43.0
^ permalink raw reply [flat|nested] 14+ messages in thread* [PATCH 09/13] docs/zh_TW: process: add maintainer-handbooks.rst translation
2026-11-06 11:35 [PATCH 00/13] docs/zh_TW: process: add translations of 13 documents Chen-Yu Yeh
` (7 preceding siblings ...)
2026-11-06 11:35 ` [PATCH 08/13] docs/zh_TW: process: add kernel-docs.rst translation Chen-Yu Yeh
@ 2026-11-06 11:35 ` Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 10/13] docs/zh_TW: process: add contribution-maturity-model.rst translation Chen-Yu Yeh
` (3 subsequent siblings)
12 siblings, 0 replies; 14+ messages in thread
From: Chen-Yu Yeh @ 2026-11-06 11:35 UTC (permalink / raw)
To: Alex Shi, Jonathan Corbet
Cc: Weijie Yuan, Dongliang Mu, Yanteng Si, linux-doc, linux-kernel,
Chen-Yu Yeh
Translate Documentation/process/maintainer-handbooks.rst into
Traditional Chinese from the current English text. The
maintainers-profile-toc directive is kept as is, as in the it_IT and
pt_BR translations, so the list of subsystem profiles is generated
from MAINTAINERS. There is no zh_CN translation of this file to
consult.
List the new file in the toctree of process/index.rst, under
"Maintainer information" as in the English index, and drop it from the
TODOList.
update to commit bda185c30593 ("docs: maintainers_include: Only show
main entry for profiles")
Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
.../translations/zh_TW/process/index.rst | 6 +++++-
.../zh_TW/process/maintainer-handbooks.rst | 20 +++++++++++++++++++
2 files changed, 25 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_TW/process/maintainer-handbooks.rst
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index 8c558bbf30e4..a4ae46350636 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -103,9 +103,13 @@ TODOList:
如何找到會接受你補丁的人。
+.. toctree::
+ :maxdepth: 1
+
+ maintainer-handbooks
+
TODOList:
-* maintainer-handbooks
* maintainers
其他材料
diff --git a/Documentation/translations/zh_TW/process/maintainer-handbooks.rst b/Documentation/translations/zh_TW/process/maintainer-handbooks.rst
new file mode 100644
index 000000000000..502cbd69251c
--- /dev/null
+++ b/Documentation/translations/zh_TW/process/maintainer-handbooks.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_TW.rst
+
+:Original: Documentation/process/maintainer-handbooks.rst
+
+子系統與維護者樹特定的開發流程說明
+==================================
+
+本文件的目的是提供子系統特定的資訊，作為一般開發流程手冊
+:ref:`Documentation/process <development_process_main>` 的補充。
+
+對開發者而言，下面列出了所有已知的子系統特定指南。如果你要貢獻的子系統
+沒有在這裡列出指南，可以就
+Documentation/maintainer/maintainer-entry-profile.rst 中提出的問題尋求釐清。
+
+對維護者而言，如果投稿經常忽略某些特定的提交標準，可以考慮把額外的要求與
+期望寫成文件。請參閱 Documentation/maintainer/maintainer-entry-profile.rst。
+
+.. maintainers-profile-toc::
--
2.43.0
^ permalink raw reply [flat|nested] 14+ messages in thread* [PATCH 10/13] docs/zh_TW: process: add contribution-maturity-model.rst translation
2026-11-06 11:35 [PATCH 00/13] docs/zh_TW: process: add translations of 13 documents Chen-Yu Yeh
` (8 preceding siblings ...)
2026-11-06 11:35 ` [PATCH 09/13] docs/zh_TW: process: add maintainer-handbooks.rst translation Chen-Yu Yeh
@ 2026-11-06 11:35 ` Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 11/13] docs/zh_TW: process: add conclave.rst translation Chen-Yu Yeh
` (2 subsequent siblings)
12 siblings, 0 replies; 14+ messages in thread
From: Chen-Yu Yeh @ 2026-11-06 11:35 UTC (permalink / raw)
To: Alex Shi, Jonathan Corbet
Cc: Weijie Yuan, Dongliang Mu, Yanteng Si, linux-doc, linux-kernel,
Chen-Yu Yeh
Translate Documentation/process/contribution-maturity-model.rst into
Traditional Chinese from the current English text. There is no zh_CN
translation of this file to consult.
List the new file in the toctree of process/index.rst, after
code-of-conduct-interpretation as in the English index, and drop it
from the TODOList.
update to commit 10a29eb658b3 ("Documentation/process: Add Linux
Kernel Contribution Maturity Model")
Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
.../process/contribution-maturity-model.rst | 83 +++++++++++++++++++
.../translations/zh_TW/process/index.rst | 2 +-
2 files changed, 84 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_TW/process/contribution-maturity-model.rst
diff --git a/Documentation/translations/zh_TW/process/contribution-maturity-model.rst b/Documentation/translations/zh_TW/process/contribution-maturity-model.rst
new file mode 100644
index 000000000000..1091aab4a7eb
--- /dev/null
+++ b/Documentation/translations/zh_TW/process/contribution-maturity-model.rst
@@ -0,0 +1,83 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_TW.rst
+
+:Original: Documentation/process/contribution-maturity-model.rst
+
+========================
+Linux 核心貢獻成熟度模型
+========================
+
+
+背景
+====
+
+在 2021 年 Linux 核心維護者高峰會（Linux Kernel Maintainers’ Summit）上，有一場
+關於招募核心維護者以及維護者接班所面臨之挑戰的 `討論
+<https://lwn.net/Articles/870581/>`_。該討論得出的部分結論包括：身為 Linux 核心
+社群一份子的公司，需要允許工程師將擔任維護者作為其工作的一部分，讓他們能夠成長
+為受人尊敬的領導者，並最終成為核心維護者。為了支持穩定的人才輸送管道，應該允許
+並鼓勵開發者承擔上游貢獻，例如審查他人的修補程式、重構核心基礎架構，以及撰寫
+文件。
+
+為此，Linux 基金會技術諮詢委員會（Technical Advisory Board，TAB）提出這份 Linux
+核心貢獻成熟度模型。這些關於參與上游社群的共同期望，旨在提升個別開發者的影響力、
+增進組織之間的協作，並改善 Linux 核心生態系的整體健康。
+
+TAB 呼籲各組織持續評估自身的開源（Open Source）成熟度模型，並承諾進行改進，以與
+本模型保持一致。為了讓評估有成效，評估應納入來自整個組織的回饋，包括管理階層以及
+各個資歷層級的開發者。秉持開源精神，我們鼓勵各組織公開其評估結果，以及改善其與
+上游社群互動的計畫。
+
+第 0 級
+=======
+
+* 不允許軟體工程師向 Linux 核心貢獻修補程式。
+
+
+第 1 級
+=======
+
+* 允許軟體工程師向 Linux 核心貢獻修補程式，無論是作為其工作職責的一部分，
+ 還是利用個人時間。
+
+第 2 級
+=======
+
+* 期望軟體工程師將貢獻 Linux 核心作為其工作職責的一部分。
+* 軟體工程師參加 Linux 相關會議將獲得支持，並視為其工作的一部分。
+* 軟體工程師的上游程式碼貢獻，將在升遷與績效考核中納入考量。
+
+第 3 級
+=======
+
+* 期望軟體工程師將審查修補程式（包括其他公司工程師所撰寫的修補程式）作為其
+ 工作職責的一部分。
+* 在 Linux 相關會議或學術會議（例如由 Linux 基金會、Usenix、ACM 等主辦的會議）
+ 上發表簡報或論文，視為工程師工作的一部分。
+* 軟體工程師的社群貢獻，將在升遷與績效考核中納入考量。
+* 組織將定期回報其開源貢獻的指標，並長期追蹤這些指標。這些指標可以只在組織內部
+ 公開，也可以由組織自行決定將部分或全部對外公開。強烈建議的指標包括：
+
+ * 依團隊或組織計算的上游核心貢獻數量（例如所有向同一位經理、總監或副總裁回報
+ 的人員）。
+ * 已做出上游貢獻的核心開發者，佔組織內核心開發者總數的百分比。
+ * 組織的伺服器和／或產品所使用的核心，與其內部核心所依據的上游核心發布日期
+ 之間的時間間隔。
+ * 內部核心中所含樹外（out-of-tree）提交的數量。
+
+第 4 級
+=======
+
+* 鼓勵軟體工程師將一部分工作時間投入上游工作（Upstream Work），其定義包括審查
+ 修補程式、擔任議程委員會（program committee）成員、改善專案的關鍵基礎架構
+ （例如撰寫或維護測試）、減少上游的技術債、撰寫文件等。
+* 軟體工程師協助籌辦 Linux 相關會議將獲得支持。
+* 組織在正式的績效考核中，將考量社群成員的回饋。
+
+第 5 級
+=======
+
+* 上游核心開發被視為正式的職位，工程師至少有三分之一的時間用於上游工作。
+* 組織將主動徵求社群成員的回饋，作為正式績效考核的一項因素。
+* 組織將定期在內部報告上游工作與直接追求商業目標之工作兩者的比例。
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index a4ae46350636..ae63704e3794 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -65,6 +65,7 @@ TODOList:
license-rules
code-of-conduct
code-of-conduct-interpretation
+ contribution-maturity-model
kernel-enforcement-statement
kernel-driver-statement
stable-api-nonsense
@@ -74,7 +75,6 @@ TODOList:
TODOList:
-* contribution-maturity-model
* generated-content
* coding-assistants
* conclave
--
2.43.0
^ permalink raw reply [flat|nested] 14+ messages in thread* [PATCH 11/13] docs/zh_TW: process: add conclave.rst translation
2026-11-06 11:35 [PATCH 00/13] docs/zh_TW: process: add translations of 13 documents Chen-Yu Yeh
` (9 preceding siblings ...)
2026-11-06 11:35 ` [PATCH 10/13] docs/zh_TW: process: add contribution-maturity-model.rst translation Chen-Yu Yeh
@ 2026-11-06 11:35 ` Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 12/13] docs/zh_TW: process: add threat-model.rst translation Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 13/13] docs/zh_TW: process: add maintainers.rst translation Chen-Yu Yeh
12 siblings, 0 replies; 14+ messages in thread
From: Chen-Yu Yeh @ 2026-11-06 11:35 UTC (permalink / raw)
To: Alex Shi, Jonathan Corbet
Cc: Weijie Yuan, Dongliang Mu, Yanteng Si, linux-doc, linux-kernel,
Chen-Yu Yeh
Translate Documentation/process/conclave.rst into Traditional Chinese
from the current English text. There is no zh_CN translation of this
file to consult.
List the new file in the toctree of process/index.rst, after
researcher-guidelines (generated-content and coding-assistants, which
precede it in the English index, are not translated), and drop it from
the TODOList.
update to commit 102606402f4f ("Documentation: Project continuity")
Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
.../translations/zh_TW/process/conclave.rst | 35 +++++++++++++++++++
.../translations/zh_TW/process/index.rst | 2 +-
2 files changed, 36 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_TW/process/conclave.rst
diff --git a/Documentation/translations/zh_TW/process/conclave.rst b/Documentation/translations/zh_TW/process/conclave.rst
new file mode 100644
index 000000000000..e237b84fd3fa
--- /dev/null
+++ b/Documentation/translations/zh_TW/process/conclave.rst
@@ -0,0 +1,35 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_TW.rst
+
+:Original: Documentation/process/conclave.rst
+
+Linux 核心專案延續性
+====================
+
+Linux 核心開發專案的分布非常廣泛，有超過 100 位維護者，各自努力讓變更在他們
+自己的儲存庫中持續推進。不過，最後一步是集中式的：變更會被拉取（pull）進主線
+儲存庫。這項工作通常由 Linus Torvalds 負責，但正如 2018 年 4.19 版發布時所
+展現的，在有需要時，也有其他人能夠承擔這項工作。
+
+若該儲存庫的維護者今後不願意或無法再承擔這項工作（包括協助交接），本專案將
+需要立即找到一位或多位接替者。完成此事的流程列於下方。$ORGANIZER 指的是最近
+一次維護者高峰會（Maintainer Summit）的籌辦人，或以 Linux 基金會（Linux
+Foundation，LF）技術諮詢委員會（Technical Advisory Board，TAB）的現任主席
+作為備援。
+
+- 在 72 小時內，$ORGANIZER 將與最近一次已結束的維護者高峰會（Maintainers
+ Summit）的受邀者展開討論。這些受邀者與 TAB 之間的會議（線上或實體皆可）將
+ 盡快安排，並以能讓最多人參與的方式進行。
+
+- 若過去 15 個月內沒有舉行過維護者高峰會，本次會議的受邀者名單將由 TAB 決定。
+
+- 本次會議的受邀者可視需要再邀請其他維護者加入。
+
+- 本次會議由 $ORGANIZER 主持，將考量頂層核心儲存庫後續管理的各種選項，且所做
+ 的選擇須符合「能最大化本專案及其社群的長期健康」此一期望。
+
+- 在兩週內，此小組的一位代表將透過 ksummit@lists.linux.dev 郵件列表，向更廣大
+ 的社群說明接下來的步驟。
+
+Linux 基金會將在 TAB 的指導下，採取必要的步驟來支持並執行此計畫。
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index ae63704e3794..d9ac35e0660f 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -72,12 +72,12 @@ TODOList:
stable-kernel-rules
management-style
researcher-guidelines
+ conclave
TODOList:
* generated-content
* coding-assistants
-* conclave
處理缺陷
--------
--
2.43.0
^ permalink raw reply [flat|nested] 14+ messages in thread* [PATCH 12/13] docs/zh_TW: process: add threat-model.rst translation
2026-11-06 11:35 [PATCH 00/13] docs/zh_TW: process: add translations of 13 documents Chen-Yu Yeh
` (10 preceding siblings ...)
2026-11-06 11:35 ` [PATCH 11/13] docs/zh_TW: process: add conclave.rst translation Chen-Yu Yeh
@ 2026-11-06 11:35 ` Chen-Yu Yeh
2026-11-06 11:35 ` [PATCH 13/13] docs/zh_TW: process: add maintainers.rst translation Chen-Yu Yeh
12 siblings, 0 replies; 14+ messages in thread
From: Chen-Yu Yeh @ 2026-11-06 11:35 UTC (permalink / raw)
To: Alex Shi, Jonathan Corbet
Cc: Weijie Yuan, Dongliang Mu, Yanteng Si, linux-doc, linux-kernel,
Chen-Yu Yeh
Translate Documentation/process/threat-model.rst into Traditional
Chinese from the current English text. There is no zh_CN translation
of this file to consult.
List the new file in the toctree of process/index.rst, after
security-bugs as in the English index, and drop it from the TODOList.
update to commit 60763c2f834d ("docs: threat-model: fix /dev/kmsg
reference")
Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
.../translations/zh_TW/process/index.rst | 5 +-
.../zh_TW/process/threat-model.rst | 187 ++++++++++++++++++
2 files changed, 188 insertions(+), 4 deletions(-)
create mode 100644 Documentation/translations/zh_TW/process/threat-model.rst
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index d9ac35e0660f..e5eb5a276fb1 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -91,13 +91,10 @@ TODOList:
debugging/index
handling-regressions
security-bugs
+ threat-model
cve
embargoed-hardware-issues
-TODOList:
-
-* threat-model
-
維護者資訊
----------
diff --git a/Documentation/translations/zh_TW/process/threat-model.rst b/Documentation/translations/zh_TW/process/threat-model.rst
new file mode 100644
index 000000000000..a28892de67ff
--- /dev/null
+++ b/Documentation/translations/zh_TW/process/threat-model.rst
@@ -0,0 +1,187 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_TW.rst
+
+:Original: Documentation/process/threat-model.rst
+
+Linux 核心威脅模型
+==================
+
+關於核心會防護、不會防護哪些東西，存在許多假設。這些假設常常讓缺陷報告產生混淆
+（:doc:`與安全相關的 <security-bugs>` 或 :doc:`與安全無關的
+<../admin-guide/reporting-issues>`），而且當某些邊界的責任在核心、發行版、管理員
+與使用者之間劃分不清時，也可能讓安全措施的落實變得複雜。
+
+本文件嘗試釐清核心在這個領域中的責任。
+
+核心的責任
+----------
+
+核心將對本地硬體資源及遠端系統的存取加以抽象化，讓多個本地使用者能夠公平分享
+授予他們的可用資源；並在底層硬體允許時，為他們的通訊以及他們正在處理或儲存的
+資料提供一定程度的機密性。
+
+核心假設底層硬體的行為符合其規格。這包括 CPU 指令集的完整性、分支預測單元與
+快取單元的透明性、記憶體管理單元（MMU）的一致性、具備 DMA 能力之周邊裝置的隔離
+（例如透過 IOMMU）、控制器中的狀態轉換、從暫存器讀取之數值的範圍、硬體已記載之
+限制的遵守等等。
+
+當硬體無法維持其規格所定的隔離時（例如 CPU 缺陷、旁路攻擊、硬體對非預期輸入的
+反應），核心通常會嘗試實作合理的緩解措施。這些措施是在硬體功能所及的範圍內盡力
+而為，目的是縮小攻擊面或提高攻擊成本；它們並不構成核心所提供的安全保證。
+
+使用者的一切活動，都在管理員的授權之下進行；管理員可以授予或拒絕各種權限，這些
+權限可能影響使用者如何使用可用資源，或其活動的機密性程度。管理員也可以將自己的
+全部或部分權限委派給某些使用者，特別是（但不限於）透過 capabilities。這一切都是
+透過設定來完成的（sysctl、檔案系統權限等）。
+
+Linux 核心套用了一組符合其威脅模型的預設設定。發行版有自己的威脅模型，並會附帶
+自己的預設設定組合，管理員可能需要加以調整（放寬或限制），以更符合自己的期望。
+
+在具備特權等級與記憶體管理單元的常見處理器上執行時，Linux 核心預設保證以下
+保護：
+
+* **以使用者為基礎的隔離**：無特權使用者可以限制在同一系統上執行的其他無特權
+ 使用者存取自己的資料。這包括：
+
+ * 儲存的資料，透過檔案系統權限
+ * 記憶體中的資料（預設情況下，其他使用者無法存取這些分頁）
+ * 行程活動（不允許對其他使用者使用 ptrace）
+ * 行程間通訊（其他使用者無法觀察透過 UNIX domain socket 或其他 IPC 機制
+ 交換的資料）。
+ * 同一系統內或與其他系統之間的網路通訊
+
+* **以 capability 為基礎的保護**：
+
+ * 不具備提升之 capabilities（包括但不限於 CAP_SYS_ADMIN）的使用者，不得變更
+ 核心的設定、記憶體或狀態，不得變更其他使用者所見的檔案系統配置，不得授予
+ 任何使用者自己所沒有的 capabilities，也不得影響系統的可用性（關機、重新
+ 開機、panic、卡住，或因無上限地耗盡資源而使系統失去回應）。
+ * 不具備 ``CAP_NET_ADMIN`` capability 的使用者，不得變更網路設定，也不得攔截
+ 或偽造來自其他使用者或其他系統的網路通訊。
+ * 不具備 ``CAP_SYS_PTRACE`` 的使用者，不得觀察其他使用者的行程活動。
+
+設定 ``CONFIG_USER_NS`` 時，核心也允許無特權使用者建立自己的使用者命名空間，並
+在其中擁有所有 capabilities，但會受到若干限制（不得執行會影響初始使用者命名空間
+的動作，例如變更時間、載入模組或掛載區塊裝置）。詳情請參閱
+``user_namespaces(7)``；使用者命名空間的各種可能性不在本文件的討論範圍內。
+
+核心也提供許多疑難排解與除錯功能，這些功能落入不當之人手中時，可能成為攻擊途徑。
+其中有些設計成可由一般本地使用者存取、風險較低（例如透過 ``/dev/kmsg`` 讀取的
+核心日誌）；有些則會暴露足夠的資訊，在大多數場合都構成風險，是否開放由管理員
+負責決定（perf events、traces）；還有一些則根本不是設計給無特權使用者存取的
+（例如 debugfs）。經管理員明確授予權限的使用者存取這些功能，並不構成安全侵害。
+
+能夠違反上述原則的缺陷，構成安全侵害。然而，必須在已經達成另一項違反之後才能
+造成違反的缺陷，只算是弱點。核心採用了若干自我保護措施，目的是在發現某些類別的
+缺陷時避免跨越安全邊界，但這些額外保護失效本身並不構成漏洞。
+
+哪些類別的問題不被視為漏洞
+--------------------------
+
+在 Linux 核心的威脅模型中，以下類別的問題 **不** 被視為 Linux 核心漏洞。不過，
+若認為核心可以做得更好，仍應回報這些問題，以便在合理可行的範圍內審查並修正，
+但它們會被當作一般缺陷處理：
+
+* **設定**：
+
+ * 過時的核心，特別是已終止維護（end-of-life）的分支，不在核心威脅模型的範圍
+ 內：管理員有責任讓自己的系統保持在最新狀態。缺陷要被認定為漏洞，必須證明它
+ 會影響仍在積極維護的版本。
+
+ * 建置層級：對核心設定的變更，且這些設定已明確記載為會降低安全等級（例如
+ ``CONFIG_NOMMU``），或僅供開發者使用。
+
+ * 作業系統層級：對命令列參數、sysctl、檔案系統權限、使用者 capabilities 的
+ 變更，或特權介面的暴露，這些變更明確地增加了暴露程度，不論是向無特權使用者
+ 提供非預設的存取，還是削弱核心落實某些保護或緩解措施的能力。例如：對 procfs
+ 或 debugfs 的寫入權限。
+
+ * 只有在使用供開發或除錯用途的功能時才會觸發的問題（例如 LOCKDEP、KASAN、
+ FAULT_INJECTION）：這些功能已知會帶來額外負擔與潛在的不穩定，並非設計供
+ 正式環境使用。
+
+ * 影響 CONFIG_STAGING 下所提供之驅動程式的問題，以及設定中標示為 EXPERIMENTAL
+ 的功能。
+
+ * 載入明確標示為不安全／損壞／staging 的模組，以及一般而言使用任何標示為
+ 實驗性或非供正式環境使用的子系統。
+
+ * 執行樹外（out-of-tree）模組或非官方的核心分支（fork）；這些問題應回報給
+ 相關的供應商。
+
+* **初始權限過高**：
+
+ * 由已經擁有執行該動作或修改該狀態所需權限的使用者所執行的動作（例如
+ ``CAP_SYS_ADMIN``、``CAP_NET_ADMIN``、``CAP_SYS_RAWIO``、
+ ``CAP_SYS_MODULE``，且沒有進一步跨越任何邊界）。
+
+ * 在使用者命名空間中執行、且沒有繞過加諸初始使用者之限制的動作（例如 ptrace
+ 的使用、訊號傳遞、資源使用、對 FS／裝置／sysctl／記憶體的存取、網路綁定、
+ 系統／網路設定等）。
+
+ * root 使用者在初始命名空間中執行的任何動作（例如寫入特權裝置時發生的核心
+ oops）。
+
+* **脫離正式環境的使用情境**：
+
+ 這涵蓋了仰賴系統雜訊為零之實驗室條件的理論性／機率性攻擊，或是需要不切實際
+ 的嘗試次數（例如數十億次）、早在成功之前就會被標準系統監控偵測到的攻擊，例如：
+
+ * 只在完全安靜的環境中才有效的亂數預測（例如只能在實驗室中猜出的 IP ID、
+ TCP 連接埠或序號）。
+
+ * 以機率性方法為基礎的活動觀察與資訊洩漏，這類方法容易受到量測雜訊影響，
+ 在正式環境的系統上實際上無法重現。
+
+ * 只能由大規模攻擊（例如暴力破解）觸發的問題，其對系統的影響使攻擊在成功之前
+ 不太可能或不可能不被察覺（例如在成功之前就耗盡所有記憶體）。
+
+ * 只在開發用的模擬器（simulator）、模擬器（emulator），或回報當時實際系統上
+ 並不存在的組合中才會出現的問題（涉及數千萬個執行緒、數萬顆 CPU、不切實際的
+ CPU 頻率、RAM 大小或磁碟容量、網路速度的問題）。
+
+ * 以及觸發成本比預期收益高出好幾個數量級的問題（例如做出功能完整的鍵盤模擬器，
+ 只為了取得某個結構中 7 個未初始化的位元組；或是涉及數百萬次連線嘗試、只為了
+ 猜出一個連接埠號碼的暴力破解方法）。
+
+* **強化措施失效**：
+
+ * 能夠繞過核心某些強化措施，但沒有可證明的利用途徑（例如繞過 ASLR、事件時序
+ 或探測，但沒有可證明的後果）。這些只是弱點，不是漏洞。
+
+ * 缺少參數檢查，以及未回報某些錯誤，但沒有立即的後果。
+
+* **隨機的資訊洩漏**：
+
+ 這指的是洩漏少量剛好存在於該處、無法由攻擊者選擇，或受到存取限制的資料片段：
+
+ * 由系統呼叫或其他介面回報的結構填充（padding）。
+
+ * 錯誤訊息中回報的識別碼、部分資料、未終止的字串。
+
+ * 核心記憶體位址／指標的洩漏並不構成可立即利用的途徑，因此不是漏洞，但仍必須
+ 回報並修正。
+
+* **不符合規格的裝置與媒體**：
+
+ 驅動程式是依照規格實作的。當裝置或儲存媒體違反其驅動程式所依據的規格時，
+ 由此產生的異常行為屬於應修正的一般缺陷，而不是漏洞，除非該驅動程式明確記載
+ 為已針對惡意輸入進行強化。因此，以下情況不被視為漏洞：
+
+ * 掛載損壞或經惡意構造的檔案系統映像檔所觸發的缺陷：掛載區塊裝置是特權操作
+ （見上文），管理員須對自己掛載的媒體負責。這包括在掛載前對映像檔執行檔案
+ 系統一致性檢查（fsck）即可解決、緩解或偵測到的問題。
+
+ * 需要修改或模擬硬體才能重現的缺陷，包括偽裝成其他裝置的假 USB 裝置，或回報
+ 超出其記載範圍之數值的裝置。
+
+* **實體存取**：
+
+ 需要實體存取機器、修改硬體，或使用專門硬體（例如邏輯分析儀、透過
+ PCI-E／Thunderbolt 進行的 DMA 攻擊工具）的問題，不在範圍之內，除非系統已明確
+ 設定了用來防禦這類攻擊的技術（例如 IOMMU）。
+
+* **功能與效能迴歸**：
+
+ 任何可以透過設定適當權限與限制來緩解的問題，都不算是漏洞。
--
2.43.0
^ permalink raw reply [flat|nested] 14+ messages in thread* [PATCH 13/13] docs/zh_TW: process: add maintainers.rst translation
2026-11-06 11:35 [PATCH 00/13] docs/zh_TW: process: add translations of 13 documents Chen-Yu Yeh
` (11 preceding siblings ...)
2026-11-06 11:35 ` [PATCH 12/13] docs/zh_TW: process: add threat-model.rst translation Chen-Yu Yeh
@ 2026-11-06 11:35 ` Chen-Yu Yeh
12 siblings, 0 replies; 14+ messages in thread
From: Chen-Yu Yeh @ 2026-11-06 11:35 UTC (permalink / raw)
To: Alex Shi, Jonathan Corbet
Cc: Weijie Yuan, Dongliang Mu, Yanteng Si, linux-doc, linux-kernel,
Chen-Yu Yeh
Documentation/process/maintainers.rst consists only of the
maintainers-include directive, which renders the top-level MAINTAINERS
file. The directive cannot be reused in the translation, as it would
define the maintainers and maintainers_table labels a second time and
duplicate the whole maintainers table.
Instead, translate the descriptive header of MAINTAINERS (the section
entry descriptions and the note on the maintainers list) into
Traditional Chinese, and point readers to the English page and the
MAINTAINERS file for the list itself. There is no zh_CN translation
of this file to consult.
List the new file in the toctree of process/index.rst, under
"Maintainer information" as in the English index, and drop it from the
TODOList.
update to commit 45a92c0b91d7 ("docs: maintainers: add SPDX license to
the file")
Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
.../translations/zh_TW/process/index.rst | 5 +-
.../zh_TW/process/maintainers.rst | 127 ++++++++++++++++++
2 files changed, 128 insertions(+), 4 deletions(-)
create mode 100644 Documentation/translations/zh_TW/process/maintainers.rst
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index e5eb5a276fb1..9ff8932760a2 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -104,10 +104,7 @@ TODOList:
:maxdepth: 1
maintainer-handbooks
-
-TODOList:
-
-* maintainers
+ maintainers
其他材料
--------
diff --git a/Documentation/translations/zh_TW/process/maintainers.rst b/Documentation/translations/zh_TW/process/maintainers.rst
new file mode 100644
index 000000000000..9110241d8a2e
--- /dev/null
+++ b/Documentation/translations/zh_TW/process/maintainers.rst
@@ -0,0 +1,127 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_TW.rst
+
+:Original: Documentation/process/maintainers.rst
+
+.. _tw_maintainers:
+
+維護者列表
+==========
+
+.. note:: 英文原文使用特殊的 ``maintainers-include`` 指令，把核心原始碼樹
+ 頂層的 ``MAINTAINERS`` 檔案整份嵌入文件中。本譯文只翻譯該檔案開頭
+ 說明各欄位的部分；實際的維護者名單請參閱英文原文
+ :ref:`Documentation/process/maintainers.rst <maintainers>`，
+ 或直接查看 ``MAINTAINERS`` 檔案。
+
+各節條目說明與建議順序
+----------------------
+
+``M:``
+ 修補程式的收件人（*Mail*）：``FullName <address@domain>``
+
+``R:``
+ 指定的審閱者（*Reviewer*）：``FullName <address@domain>``
+
+ 發送修補程式時應副本（CC）給這些審閱者。
+
+``L:``
+ 與此領域相關的郵件列表（*Mailing list*）
+
+``S:``
+ 狀態（*Status*），為下列其中之一：
+
+ Supported
+ 有人實際受僱照顧這部分。
+
+ Maintained
+ 有人實際在照顧它。
+
+ Odd Fixes
+ 有維護者，但他們沒有時間做太多事，只會偶爾加入一些修補程式。
+ 見下文。
+
+ Orphan
+ 目前沒有維護者［不過也許你在撰寫新程式碼的同時，可以接下這個角色］。
+
+ Obsolete
+ 舊程式碼。標記為 obsolete 的東西通常表示它已經被更好的系統取代，
+ 你應該改用那個系統。
+
+``W:``
+ 提供狀態與資訊的網頁（*Web-page*）
+
+``Q:``
+ *Patchwork* 網頁式修補程式追蹤系統的網站
+
+``B:``
+ 回報缺陷（*bugs*）的 URI。可以是含有詳細回報說明的網頁、缺陷追蹤系統的
+ 直接連結，或 mailto: URI。
+
+``C:``
+ 聊天（*chat*）的 URI，包含開發者通常聚集的協定、伺服器與頻道，例如
+ ``irc://server/channel``。
+
+``P:``
+ 子系統概要（*Subsystem Profile*）文件，說明向該子系統提交修補程式的
+ 更多細節。可以是核心原始碼樹中 Documentation/ 底下的 .rst 檔案，或是
+ 一個 URI。詳見 Documentation/maintainer/maintainer-entry-profile.rst。
+
+``T:``
+ 原始碼管理（*SCM*）樹的類型與位置。
+
+ 類型為下列其中之一：git、hg、quilt、stgit、topgit
+
+``F:``
+ 檔案（*Files*）與目錄的萬用字元模式。
+
+ 結尾的斜線表示包含該目錄下的所有檔案，以及其子目錄中的檔案。
+
+ - ``F: drivers/net/``：drivers/net 中及其下各層的所有檔案
+ - ``F: drivers/net/*``：drivers/net 中的所有檔案，但不含其下各層
+ - ``F: */net/*``：「任何頂層目錄」/net 中的所有檔案
+ - ``F: fs/**/*foo*.c``：fs 任何子目錄中所有符合 ``*foo*.c`` 的檔案
+
+ 每行一個模式，可以有多行 F:。
+
+``X:``
+ 排除（*Excluded*）不由此條目維護的檔案與目錄，規則與 F: 相同。排除規則
+ 會先於檔案比對進行檢查。可用來排除特定子目錄，例如：
+
+ - ``F: net/``
+ - ``X: net/ipv6/``
+
+ 會比對 net/ 中及其下各層的所有檔案，但排除 net/ipv6/。
+
+``N:``
+ 檔案與目錄的正規表示式（*Regex*）模式。
+
+ - ``N: [^a-z]tegra``：路徑中含有 tegra 的所有檔案（不包括像 integrator
+ 這樣的檔案）
+
+ 每行一個模式，可以有多行 N:。
+
+ scripts/get_maintainer.pl 對於符合 F: 模式的檔案與符合 N: 模式的檔案，
+ 處理方式不同。預設情況下，比對到 F: 模式時，get_maintainer 不會查看
+ git log 歷史；比對到 N: 模式時，則會利用 git log 歷史，一併通知在 git
+ 提交中留有簽名的人。
+
+``K:``
+ 在修補程式或檔案中比對的內容正規表示式（*Content regex*，perl 擴充語法）。
+ 例如：
+
+ - ``K: of_get_profile``：比對含有「of_get_profile」的修補程式或檔案
+ - ``K: \b(printk|pr_(info|err))\b``：比對含有 printk、pr_info 或 pr_err
+ 其中一個或多個字詞的修補程式或檔案
+
+ 每行一個正規表示式模式，可以有多行 K:。
+
+維護者名單
+----------
+
+.. note:: 閱讀此名單時，請先尋找最精確的領域。新增條目時，請保持條目依
+ 字母順序排列。
+
+完整的維護者名單（依子系統排列的表格）請參閱英文原文
+:ref:`Documentation/process/maintainers.rst <maintainers_table>`。
--
2.43.0
^ permalink raw reply [flat|nested] 14+ messages in thread