[PATCH 24/25] docs/zh_TW: process: sync submit-checklist.rst with the English original

[Chen-Yu Yeh <chenyou910331@gmail.com>]

The translation carries no "update to commit" marker.  It was converted
from zh_CN and, apart from a few later spot fixes (CONFIG_SLUB_DEBUG,
the abi.rst reference), still follows the flat 24-item list from before
2021.  Bring it in line with the current English text:

- regroup the items into the "Review your code", "Review Kconfig
  changes", "Provide documentation", "Check your code with tools",
  "Build your code" and "Test your code" sections, following
  commit 5969fbf30274 ("docs: submit-checklist: structure by category")
  and commit 47c67ec1e8ef ("docs: submit-checklist: use subheadings")
- fold the ppc64 item into the cross-compile item and replace it with
  the word size and endianness note from commit 2783096fb1dd ("docs:
  submit-checklist: Expand on build tests against different word sizes")
- test against the latest linux-next tag instead of the -mm patchset,
  turn the checkstack note block into a sentence, and drop the htmldocs
  sentence from the kernel-doc item, as in commit 5969fbf30274 ("docs:
  submit-checklist: structure by category")
- use KCFLAGS instead of EXTRA-CFLAGS, following
  commit 163ba35ff371 ("doc: use KCFLAGS instead of EXTRA_CFLAGS to pass
  flags from command line")
- drop the sparse.rst pointer that the original does not have

Also fix the opening paragraph, which said the checklist is provided
in submitting-patches.rst rather than going beyond it, link
submitting-patches.rst and coding-style.rst through their zh_TW labels
and kernel-doc through the label used by the original, and retranslate
the text with Taiwanese terminology (內核→核心, 補丁→修補程式,
代碼→程式碼, 內存→記憶體, 構建→建置, 接口→介面, 菜單→選單, 默認→預設,
堆棧→堆疊, 字節→位元組, 體系結構→架構, ...).

update to commit 5a63f0369bda ("docs/.../submit-checklist: Use
Documentation/admin-guide/abi.rst for cross-ref of README")

Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
 .../zh_TW/process/submit-checklist.rst        | 159 ++++++++++--------
 1 file changed, 91 insertions(+), 68 deletions(-)

diff --git a/Documentation/translations/zh_TW/process/submit-checklist.rst b/Documentation/translations/zh_TW/process/submit-checklist.rst
index 452fecc7c425..7c25b99288f2 100644
--- a/Documentation/translations/zh_TW/process/submit-checklist.rst
+++ b/Documentation/translations/zh_TW/process/submit-checklist.rst
@@ -6,105 +6,128 @@
 
 .. _tw_submitchecklist:
 
-Linux內核補丁提交檢查單
-~~~~~~~~~~~~~~~~~~~~~~~
+================================
+Linux 核心修補程式提交檢查清單
+================================
 
-如果開發人員希望看到他們的內核補丁提交更快地被接受，那麼他們應該做一些基本
-的事情。
+以下是開發者若希望自己提交的核心修補程式能更快被接受，應該做到的一些基本
+事項。
 
-這些都是在 Documentation/translations/zh_CN/process/submitting-patches.rst
-和其他有關提交Linux內核補丁的文檔中提供的。
+這些事項是在
+:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst
+<tw_submittingpatches>`
+及其他關於提交 Linux 核心修補程式的文件所提供的內容之外，還要額外做到的。
 
-1) 如果使用工具，則包括定義/聲明該工具的文件。不要依賴其他頭文件來引入您使用
-   的頭文件。
+審查你的程式碼
+==============
 
-2) 乾淨的編譯：
+1) 如果你使用了某項功能，就 #include 定義／宣告該功能的檔案。不要依賴其他
+   標頭檔幫你引入你所用到的標頭檔。
 
-   a) 使用合適的 ``CONFIG`` 選項 ``=y``、``=m`` 和 ``=n`` 。沒有 ``gcc``
-      警告/錯誤，沒有鏈接器警告/錯誤。
+2) 依照
+   :ref:`Documentation/translations/zh_TW/process/coding-style.rst
+   <tw_codingstyle>`
+   所述，檢查你的修補程式是否符合一般的程式碼風格。
 
-   b) 通過 ``allnoconfig`` 、 ``allmodconfig``
+3) 所有記憶體屏障（例如 ``barrier()``、``rmb()``、``wmb()``）都需要在原始碼
+   中加上註解，說明它們所做事情的邏輯及原因。
 
-   c) 使用 ``O=builddir`` 時可以成功編譯
+審查 Kconfig 變更
+=================
 
-   d) 任何 Documentation/ 下的變更都能成功構建且不引入新警告/錯誤。
-      用 ``make htmldocs`` 或 ``make pdfdocs`` 檢驗構建情況並修復問題。
+1) 任何新增或修改的 ``CONFIG`` 選項都不應弄亂設定選單，且預設應為關閉，
+   除非符合 ``Documentation/kbuild/kconfig-language.rst`` 中
+   Menu attributes: default value 一節所記載的例外條件。
 
-3) 通過使用本地交叉編譯工具或其他一些構建設施在多個CPU體系結構上構建。
+2) 所有新的 ``Kconfig`` 選項都有說明文字。
 
-4) PPC64是一種很好的交叉編譯檢查體系結構，因爲它傾向於對64位的數使用無符號
-   長整型。
+3) 已針對相關的 ``Kconfig`` 組合仔細審查過。這一點很難單靠測試做對，
+   在這裡多動腦是值得的。
 
-5) 按 Documentation/translations/zh_CN/process/coding-style.rst 所述檢查您的
-   補丁是否爲常規樣式。在提交之前使用補丁樣式檢查器 ``scripts/checkpatch.pl``
-   檢查是否有輕微的衝突。您應該能夠處理您的補丁中存在的所有
-   違規行爲。
+提供文件
+========
 
-6) 任何新的或修改過的 ``CONFIG`` 選項都不應搞亂配置菜單，並默認爲關閉，除非
-   它們符合 ``Documentation/kbuild/kconfig-language.rst`` 菜單屬性：默認值中
-   記錄的例外條件。
+1) 加入 :ref:`kernel-doc <kernel_doc>` 來為全域核心 API 撰寫文件。
+   （static 函式不需要，但寫了也可以。）
 
-7) 所有新的 ``kconfig`` 選項都有幫助文本。
+2) 所有新的 ``/proc`` 項目都在 ``Documentation/`` 下有文件記載。
 
-8) 已仔細審查了相關的 ``Kconfig`` 組合。這很難用測試來糾正——腦力在這裏是有
-   回報的。
+3) 所有新的核心開機參數都記載於
+   ``Documentation/admin-guide/kernel-parameters.rst``。
 
-9) 通過 sparse 清查。
-   （參見 Documentation/translations/zh_CN/dev-tools/sparse.rst ）
+4) 所有新的模組參數都用 ``MODULE_PARM_DESC()`` 記載。
 
-10) 使用 ``make checkstack`` 並修復他們發現的任何問題。
+5) 所有新的使用者空間介面都記載於 ``Documentation/ABI/``。
+   詳情請參閱 Documentation/admin-guide/abi.rst
+   （或 ``Documentation/ABI/README``）。
+   更改使用者空間介面的修補程式應該副本（CC）給
+   linux-api@vger.kernel.org\ 。
 
-    .. note::
+6) 如果修補程式新增了任何 ioctl，也要更新
+   ``Documentation/userspace-api/ioctl/ioctl-number.rst``。
 
-        ``checkstack`` 並不會明確指出問題，但是任何一個在堆棧上使用超過512
-        字節的函數都可以進行更改。
+使用工具檢查你的程式碼
+======================
 
-11) 包括 :ref:`kernel-doc <kernel_doc_zh>` 內核文檔以記錄全局內核API。（靜態
-    函數不需要，但也可以。）使用 ``make htmldocs`` 或 ``make pdfdocs`` 檢查
-    :ref:`kernel-doc <kernel_doc_zh>` 並修復任何問題。
+1) 提交前先用修補程式風格檢查器（``scripts/checkpatch.pl``）檢查有無輕微的
+   違規。對於修補程式中仍留下的每一項違規，你都應該能說明理由。
 
-12) 通過以下選項同時啓用的測試： ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
-    ``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
-    ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``,
-    ``CONFIG_PROVE_RCU`` 和 ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` 。
+2) 用 sparse 檢查時乾淨無誤。
 
-13) 在 ``CONFIG_SMP``, ``CONFIG_PREEMPT`` 開啓和關閉的情況下都進行構建和運行
-    時測試。
+3) 使用 ``make checkstack`` 並修正它找到的任何問題。
+   請注意 ``checkstack`` 不會明確指出問題，但任何在堆疊上使用超過 512 位元組
+   的函式，都是應該修改的候選對象。
 
-14) 所有代碼路徑都已在啓用所有死鎖檢測（lockdep）功能的情況下運行。
+建置你的程式碼
+==============
 
-15) 所有新的 ``/proc`` 條目都記錄在 ``Documentation/``
+1) 乾淨地建置：
 
-16) 所有新的內核引導參數都記錄在
-    Documentation/admin-guide/kernel-parameters.rst 中。
+  a) 使用適用或修改過的 ``CONFIG`` 選項 ``=y``、``=m`` 與 ``=n``。
+     沒有 ``gcc`` 警告／錯誤，也沒有連結器警告／錯誤。
 
-17) 所有新的模塊參數都記錄在 ``MODULE_PARM_DESC()``
+  b) 通過 ``allnoconfig``、``allmodconfig``
 
-18) 所有新的用戶空間接口都記錄在 ``Documentation/ABI/`` 中。有關詳細信息，
-    請參閱 Documentation/admin-guide/abi.rst (或 ``Documentation/ABI/README``)。
-    更改用戶空間接口的補丁應該抄送 linux-api@vger.kernel.org\ 。
+  c) 使用 ``O=builddir`` 時可以成功建置
 
-19) 已通過至少注入slab和page分配失敗進行檢查。請參閱 ``Documentation/fault-injection/`` 。
-    如果新代碼是實質性的，那麼添加子系統特定的故障注入可能是合適的。
+  d) Documentation/ 下的任何變更都能成功建置，且不產生新的警告／錯誤。
+     使用 ``make htmldocs`` 或 ``make pdfdocs`` 檢查建置結果，並修正任何
+     問題。
 
-20) 新添加的代碼已經用 ``gcc -W`` 編譯（使用 ``make EXTRA-CFLAGS=-W`` ）。這
-    將產生大量噪聲，但對於查找諸如“警告：有符號和無符號之間的比較”之類的錯誤
-    很有用。
+2) 使用本機的交叉編譯工具或其他建置環境（build farm），在多種 CPU 架構上
+   建置。
+   請注意，針對不同字組大小（32 位元與 64 位元）及不同位元組順序（big-endian
+   與 little-endian）的架構進行測試，能有效找出各種可攜性問題；這些問題源自
+   對可表示的數值範圍、資料對齊或位元組順序等的錯誤假設。
 
-21) 在它被合併到-mm補丁集中之後進行測試，以確保它仍然與所有其他排隊的補丁以
-    及VM、VFS和其他子系統中的各種更改一起工作。
+3) 新加入的程式碼已用 ``gcc -W`` 編譯過（使用 ``make KCFLAGS=-W``）。這會
+   產生大量雜訊，但很適合用來找出像「warning: comparison between signed and
+   unsigned」這類的錯誤。
 
-22) 所有內存屏障（例如 ``barrier()``, ``rmb()``, ``wmb()`` ）都需要源代碼注
-    釋來解釋它們正在執行的操作及其原因的邏輯。
+4) 如果你修改的原始碼依賴或使用了與下列 ``Kconfig`` 符號相關的任何核心 API
+   或功能，就要在停用相關 ``Kconfig`` 符號及／或設為 ``=m`` （如果有此選項）
+   的情況下，測試多種建置組合〔不必同時全部停用，只要各種／隨機的組合即可〕：
 
-23) 如果補丁添加了任何ioctl，那麼也要更新
-    ``Documentation/userspace-api/ioctl/ioctl-number.rst`` 。
+   ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``,
+   ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``,
+   ``CONFIG_NET``, ``CONFIG_INET=n`` （但後者需搭配 ``CONFIG_NET=y``）。
 
-24) 如果修改後的源代碼依賴或使用與以下 ``Kconfig`` 符號相關的任何內核API或
-    功能，則在禁用相關 ``Kconfig`` 符號和/或 ``=m`` （如果該選項可用）的情況
-    下測試以下多個構建[並非所有這些都同時存在，只是它們的各種/隨機組合]：
+測試你的程式碼
+==============
 
-    ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``,
-    ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``,
-    ``CONFIG_NET``, ``CONFIG_INET=n`` （但是最後一個需要 ``CONFIG_NET=y`` ）。
+1) 已在同時啟用 ``CONFIG_PREEMPT``、``CONFIG_DEBUG_PREEMPT``、
+   ``CONFIG_SLUB_DEBUG``、``CONFIG_DEBUG_PAGEALLOC``、``CONFIG_DEBUG_MUTEXES``、
+   ``CONFIG_DEBUG_SPINLOCK``、``CONFIG_DEBUG_ATOMIC_SLEEP``、
+   ``CONFIG_PROVE_RCU`` 與 ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` 的情況下測試過。
 
+2) 已在啟用與不啟用 ``CONFIG_SMP`` 及 ``CONFIG_PREEMPT.`` 的情況下，進行過
+   建置與執行期測試。
+
+3) 所有程式碼路徑都已在啟用所有 lockdep 功能的情況下執行過。
+
+4) 已至少透過注入 slab 與分頁配置失敗進行過檢查。請參閱
+   ``Documentation/fault-injection/``。
+   如果新程式碼的份量很大，加入子系統專屬的故障注入可能也是適當的。
+
+5) 已用 linux-next 最新的標籤測試過，確保它仍能與所有其他排隊中的修補程式，
+   以及 VM、VFS 和其他子系統的各種變更一起正常運作。
-- 
2.43.0