Received: by 2002:a05:6359:6284:b0:131:369:b2a3 with SMTP id se4csp3094589rwb; Mon, 7 Aug 2023 08:10:51 -0700 (PDT) X-Received: by 2002:a05:651c:14c:b0:2b7:3656:c594 with SMTP id c12-20020a05651c014c00b002b73656c594mr6876195ljd.3.1691420811977; Mon, 07 Aug 2023 08:06:51 -0700 (PDT) X-Google-Smtp-Source: AGHT+IEW2uqI/sspHGot6iIFAe+pNjQn1VAlfmj1VYQZ5ICnA4NDQE7Hpmma1osu0F14IxsR+Krp X-Received: by 2002:a05:651c:14c:b0:2b7:3656:c594 with SMTP id c12-20020a05651c014c00b002b73656c594mr6875927ljd.3.1691420805498; Mon, 07 Aug 2023 08:06:45 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1691420805; cv=none; d=google.com; s=arc-20160816; b=PAn+T9vKY02Q06IxOWNKBguo7EMGzantqTCOnrX46F++tfEmQFiCDVc40oT5dKmm86 N1qE9Ks+iCk0Phy2d+dFVnugqyuH2VoAsx27pYNXdcKOxE/NWK0ihl4hf4a6z8UypaxF A46MrRAFNVU5ovP/2hBbXN8u06mZmCPK9L/b2KKv7uZ+Kck8tFej7tZoDY87e9kkX0sD gxQPXYy5UKgXDkSvVvNzXUD3CwGQcfbX4O6/AurXjuWDnx0V1mTvI/VTU9pKGtUKE/dB 1pDKksxrzWYga6HKPa1naoo3j6cj+pz8IKwj6BPTpFjz6l1V8QLA+5NV2Lp6N5BbGDUp of7g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=8aUkmYVh0tSDd184L6zgFWg8YUiSJ6cv2Tg9pQlwrd4=; fh=6FHt6x0BqmAILtdU2uNV7cakfuU3h6xUrU3SVewvOPk=; b=xT1AHKFgVW/oFC4aHA18l2/3U0YsEtkeT3WO7j/JhJd1uwZL6kZgxF/Ny0c58YKuz/ vmhIigZFxllkCN4PJqTiu5DlhMo4vI4Tv7MJLNHXHqEcZMlHzD+H1GXUDFyGAZsdLRVj 8drqqR8+xtzfQuAsO4cjIrXtip70Rs0qkGuAalxJAcS0QMTj7fyf+OA3HS9wYxJD47Dg gphzH8EPqbKPHz0NFNt6GZfp6ip0R8mVXjcTVPoJRjTsEuz4fOtTGiSWNxshsUudoI0+ MW9m7KzUFhuh2WFx+BPPYE/V+T7V5Sbtbac+wATdIvdX8dRg4xotSFbKoPC4wzadRVfq ShYQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gmail.com header.s=20221208 header.b=o68oUlGH; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Return-Path: Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id e4-20020a170906248400b00988da29a08fsi5517506ejb.841.2023.08.07.08.06.19; Mon, 07 Aug 2023 08:06:45 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@gmail.com header.s=20221208 header.b=o68oUlGH; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233217AbjHGMB0 (ORCPT + 99 others); Mon, 7 Aug 2023 08:01:26 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37536 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233197AbjHGMA6 (ORCPT ); Mon, 7 Aug 2023 08:00:58 -0400 Received: from mail-pf1-x442.google.com (mail-pf1-x442.google.com [IPv6:2607:f8b0:4864:20::442]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id BC8F51721; Mon, 7 Aug 2023 05:00:42 -0700 (PDT) Received: by mail-pf1-x442.google.com with SMTP id d2e1a72fcca58-686ea67195dso3105880b3a.2; Mon, 07 Aug 2023 05:00:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1691409641; x=1692014441; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=8aUkmYVh0tSDd184L6zgFWg8YUiSJ6cv2Tg9pQlwrd4=; b=o68oUlGHG8vE6thzvuki0uW93HI9zpJWI7KQ7jbaaSpTB3U5GRGBiqP1jp+kRLDxW9 xWyhCoY8m16MFukHnn9I74Y0bwyBSYvVn+3JaHNaLXAWkhi+2pJZlpBlUFRUfOb05Apv XUiFGTVeoL23p/59EueEDrWJv6QFpmdDYNJzacBGr9pAah+AoNqFDN3w9DxhuUJhnu3w vuruS1c8KcG3TsHaj9B8U5EzoWfL4eoqpR/I7+mwoOS63vADkvcOit9SNla7AgC5m2Ym qel07sindqqwXUUWrOhajUj3jReX3hFHXdr8p06IXSNk4L8dhc+Y23sctY9+7Zp4ITQp A+Yg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1691409641; x=1692014441; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=8aUkmYVh0tSDd184L6zgFWg8YUiSJ6cv2Tg9pQlwrd4=; b=XAhegJx9jI/rZQJqNyD+r3S6EEoHTpOrDL6HztKefMCtE3nteXsE4vsIkmWH4vK1nV OGbH7lGT5AzkhY7cOHpYJO4mahRvPJQabEhTd3RbMWQai4Ln0NqDbFN59XefL6Zq3xa1 mAhyvKV33Rv6UkabAXlHzWFus4N6gIFkanqOeef/w403MSdJi+so4grzUccCP1q3YJVw fZjCgOIRJ03OTx4z66KLCMaOri6Xno0RA0bM8OCiXxYuiw6y7koGXq0QtXcPTBgvyFL/ yAdckjvRXMtHaNOanFhHtvrjGxFD8YYUFoXYjzmdqzPRJzqLjR/Z9ETnIr4m38AWUUDG AIfg== X-Gm-Message-State: AOJu0YxnKdy7FYyZKI1I8P4KUNVVt84Ish5mO5ddSNzckZGpp7gBvV2L 62Ri7nxhsu61OSqQxF5NdcI= X-Received: by 2002:a05:6a00:b84:b0:67d:22a6:2f54 with SMTP id g4-20020a056a000b8400b0067d22a62f54mr10854343pfj.31.1691409637681; Mon, 07 Aug 2023 05:00:37 -0700 (PDT) Received: from localhost.localdomain ([113.251.7.202]) by smtp.gmail.com with ESMTPSA id e16-20020a62ee10000000b00686940bfb77sm6013108pfi.71.2023.08.07.05.00.33 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 07 Aug 2023 05:00:36 -0700 (PDT) From: Hu Haowen To: corbet@lwn.net Cc: Hu Haowen , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v3 5/6] docs/zh_TW: update process Date: Mon, 7 Aug 2023 20:00:05 +0800 Message-Id: <20230807120006.6361-6-src.res.211@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230807120006.6361-1-src.res.211@gmail.com> References: <20230807120006.6361-1-src.res.211@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-1.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_ENVFROM_END_DIGIT, FREEMAIL_FROM,RCVD_IN_DNSWL_NONE,SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Update zh_TW's process documentation concentrating on the following aspects: * The file tree structure changes of the main documentation; * Some changes and ideas from zh_CN translation; * Removal for several obsoleted contents within the zh_TW translation or those which are not exising anymore in the main documentation. * Replacements for some incorrect words and phrases in traditional Chinese or those which are odd within their context being hard for readers to comprehend. Signed-off-by: Hu Haowen --- .../translations/zh_TW/process/1.Intro.rst | 84 +- .../translations/zh_TW/process/2.Process.rst | 130 +-- .../zh_TW/process/3.Early-stage.rst | 44 +- .../translations/zh_TW/process/4.Coding.rst | 104 +-- .../translations/zh_TW/process/5.Posting.rst | 80 +- .../zh_TW/process/6.Followthrough.rst | 46 +- .../zh_TW/process/7.AdvancedTopics.rst | 56 +- .../zh_TW/process/8.Conclusion.rst | 14 +- .../code-of-conduct-interpretation.rst | 54 +- .../zh_TW/process/code-of-conduct.rst | 20 +- .../zh_TW/process/coding-style.rst | 400 ++++++---- .../zh_TW/process/development-process.rst | 2 +- .../zh_TW/process/email-clients.rst | 273 ++++--- .../process/embargoed-hardware-issues.rst | 78 +- .../translations/zh_TW/process/howto.rst | 156 ++-- .../translations/zh_TW/process/index.rst | 5 +- .../zh_TW/process/kernel-driver-statement.rst | 2 +- .../process/kernel-enforcement-statement.rst | 14 +- .../zh_TW/process/license-rules.rst | 54 +- .../zh_TW/process/management-style.rst | 64 +- .../zh_TW/process/stable-api-nonsense.rst | 86 +- .../zh_TW/process/stable-kernel-rules.rst | 36 +- .../zh_TW/process/submit-checklist.rst | 92 ++- .../zh_TW/process/submitting-patches.rst | 755 +++++++++--------- .../process/volatile-considered-harmful.rst | 32 +- 25 files changed, 1441 insertions(+), 1240 deletions(-) diff --git a/Documentation/translations/zh_TW/process/1.Intro.rst b/Documentation/translations/zh_TW/process/1.Intro.rst index ca2b931be6c5..53f3f3135d47 100644 --- a/Documentation/translations/zh_TW/process/1.Intro.rst +++ b/Documentation/translations/zh_TW/process/1.Intro.rst @@ -22,55 +22,55 @@ -------- 本節的其餘部分涵蓋了內核開發的過程，以及開發人員及其僱主在這方面可能遇到的 -各種問題。有很多原因使內核代碼應被合併到正式的（「主線」）內核中，包括對用戶 +各種問題。有很多原因使內核代碼應被合併到正式的（“主線”）內核中，包括對用戶 的自動可用性、多種形式的社區支持以及影響內核開發方向的能力。提供給Linux內核 的代碼必須在與GPL兼容的許可證下可用。 -:ref:`tw_development_process` 介紹了開發過程、內核發布周期和合併窗口的機制。 -涵蓋了補丁開發、審查和合併周期中的各個階段。還有一些關於工具和郵件列表的討論？ +:ref:`cn_development_process` 介紹了開發過程、內核發佈週期和合並窗口的機制。 +涵蓋了補丁開發、審查和合並週期中的各個階段。還有一些關於工具和郵件列表的討論？ 鼓勵希望開始內核開發的開發人員跟蹤並修復缺陷以作爲初步練習。 -:ref:`tw_development_early_stage` 包括項目的早期規劃，重點是儘快讓開發社區 +:ref:`cn_development_early_stage` 包括項目的早期規劃，重點是儘快讓開發社區 參與進來。 -:ref:`tw_development_coding` 是關於編程過程的；介紹了其他開發人員遇到的幾個 +:ref:`cn_development_coding` 是關於編程過程的；介紹了其他開發人員遇到的幾個 陷阱。也涵蓋了對補丁的一些要求，並且介紹了一些工具，這些工具有助於確保內核 補丁是正確的。 -:ref:`tw_development_posting` 描述發布補丁以供評審的過程。爲了讓開發社區能 +:ref:`cn_development_posting` 描述發佈補丁以供評審的過程。爲了讓開發社區能 認真對待，補丁必須被正確格式化和描述，並且必須發送到正確的地方。遵循本節中的 建議有助於確保您的工作能被較好地接納。 -:ref:`tw_development_followthrough` 介紹了發布補丁之後發生的事情；工作在這時 +:ref:`cn_development_followthrough` 介紹了發佈補丁之後發生的事情；工作在這時 還遠遠沒有完成。與審閱者一起工作是開發過程中的一個重要部分；本節提供了一些 關於如何在這個重要階段避免問題的提示。當補丁被合併到主線中時，開發人員要注意 不要假定任務已經完成。 -:ref:`tw_development_advancedtopics` 介紹了兩個「高級」主題：使用Git管理補丁 -和查看其他人發布的補丁。 +:ref:`cn_development_advancedtopics` 介紹了兩個“高級”主題：使用Git管理補丁 +和查看其他人發佈的補丁。 -:ref:`tw_development_conclusion` 總結了有關內核開發的更多信息，附帶有相關資源 -連結。 +:ref:`cn_development_conclusion` 總結了有關內核開發的更多信息，附帶有相關資源 +鏈接。 這個文檔是關於什麼的 -------------------- Linux內核有超過800萬行代碼，每個版本的貢獻者超過1000人，是現存最大、最活躍的 -免費軟體項目之一。從1991年開始，這個內核已經發展成爲一個最好的作業系統組件， -運行在袖珍數位音樂播放器、桌上型電腦、現存最大的超級計算機以及所有類型的系統上。 +免費軟件項目之一。從1991年開始，這個內核已經發展成爲一個最好的操作系統組件， +運行在袖珍數字音樂播放器、臺式電腦、現存最大的超級計算機以及所有類型的系統上。 它是一種適用於幾乎任何情況的健壯、高效和可擴展的解決方案。 -隨著Linux的發展，希望參與其開發的開發人員（和公司）的數量也在增加。硬體供應商 +隨着Linux的發展，希望參與其開發的開發人員（和公司）的數量也在增加。硬件供應商 希望確保Linux能夠很好地支持他們的產品，使這些產品對Linux用戶具有吸引力。嵌入 式系統供應商使用Linux作爲集成產品的組件，希望Linux能夠儘可能地勝任手頭的任務。 -分銷商和其他基於Linux的軟體供應商切實關心Linux內核的功能、性能和可靠性。最終 +分銷商和其他基於Linux的軟件供應商切實關心Linux內核的功能、性能和可靠性。最終 用戶也常常希望修改Linux，使之能更好地滿足他們的需求。 Linux最引人注目的特性之一是這些開發人員可以訪問它；任何具備必要技能的人都可以 -改進Linux並影響其開發方向。專有產品不能提供這種開放性，這是自由軟體的一個特點。 -如果有什麼不同的話，那就是內核比大多數其他自由軟體項目更開放。一個典型的三個 -月內核開發周期可以涉及1000多個開發人員，他們爲100多個不同的公司（或者根本不 +改進Linux並影響其開發方向。專有產品不能提供這種開放性，這是自由軟件的一個特點。 +如果有什麼不同的話，那就是內核比大多數其他自由軟件項目更開放。一個典型的三個 +月內核開發週期可以涉及1000多個開發人員，他們爲100多個不同的公司（或者根本不 隸屬公司）工作。 與內核開發社區合作並不是特別困難。但儘管如此，仍有許多潛在的貢獻者在嘗試做 @@ -79,7 +79,7 @@ Linux最引人注目的特性之一是這些開發人員可以訪問它；任何 過程與專有的開發模式有很大的不同也就不足爲奇了。 對於新開發人員來說，內核的開發過程可能會讓人感到奇怪和恐懼，但這背後有充分的 -理由和堅實的經驗。一個不了解內核社區工作方式的開發人員（或者更糟的是，他們 +理由和堅實的經驗。一個不瞭解內核社區工作方式的開發人員（或者更糟的是，他們 試圖拋棄或規避之）會得到令人沮喪的體驗。開發社區在幫助那些試圖學習的人的同時， 沒有時間幫助那些不願意傾聽或不關心開發過程的人。 @@ -102,20 +102,20 @@ Andrew Morton, Andrew Price, Tsugikazu Shibata 和 Jochen Voß 。 -------------------- 有些公司和開發人員偶爾會想，爲什麼他們要費心學習如何與內核社區合作，並將代碼 -放入主線內核（「主線」是由Linus Torvalds維護的內核，Linux發行商將其用作基礎）。 +放入主線內核（“主線”是由Linus Torvalds維護的內核，Linux發行商將其用作基礎）。 在短期內，貢獻代碼看起來像是一種可以避免的開銷；維護獨立代碼並直接支持用戶 -似乎更容易。事實上，保持代碼獨立（「樹外」）是在經濟上是錯誤的。 +似乎更容易。事實上，保持代碼獨立（“樹外”）是在經濟上是錯誤的。 爲了說明樹外代碼成本，下面給出內核開發過程的一些相關方面；本文稍後將更詳細地 討論其中的大部分內容。請考慮： - 所有Linux用戶都可以使用合併到主線內核中的代碼。它將自動出現在所有啓用它的 - 發行版上。無需驅動程序磁碟、額外下載，也不需要爲多個發行版的多個版本提供 + 發行版上。無需驅動程序磁盤、額外下載，也不需要爲多個發行版的多個版本提供 支持；這一切將方便所有開發人員和用戶。併入主線解決了大量的分發和支持問題。 - 當內核開發人員努力維護一個穩定的用戶空間接口時，內核內部API處於不斷變化之中。 不維持穩定的內部接口是一個慎重的設計決策；它允許在任何時候進行基本的改進， - 並產出更高質量的代碼。但該策略導致結果是，若要使用新的內核，任何樹外代碼都 + 併產出更高質量的代碼。但該策略導致結果是，若要使用新的內核，任何樹外代碼都 需要持續的維護。維護樹外代碼會需要大量的工作才能使代碼保持正常運行。 相反，位於主線中的代碼不需要這樣做，因爲基本規則要求進行API更改的任何開發 @@ -140,60 +140,60 @@ Andrew Morton, Andrew Price, Tsugikazu Shibata 和 Jochen Voß 。 - 代碼的貢獻是使整個流程工作的根本。通過貢獻代碼，您可以向內核添加新功能，並 提供其他內核開發人員使用的功能和示例。如果您已經爲Linux開發了代碼（或者正在 - 考慮這樣做），那麼您顯然對這個平台的持續成功感興趣；貢獻代碼是確保成功的 + 考慮這樣做），那麼您顯然對這個平臺的持續成功感興趣；貢獻代碼是確保成功的 最好方法之一。 -上述所有理由都適用於任何樹外內核代碼，包括以專有的、僅二進位形式分發的代碼。 -然而，在考慮任何類型的純二進位內核代碼分布之前，還需要考慮其他因素。包括： +上述所有理由都適用於任何樹外內核代碼，包括以專有的、僅二進制形式分發的代碼。 +然而，在考慮任何類型的純二進制內核代碼分佈之前，還需要考慮其他因素。包括： - 圍繞專有內核模塊分發的法律問題其實較爲模糊；相當多的內核版權所有者認爲， - 大多數僅二進位的模塊是內核的派生產品，因此，它們的分發違反了GNU通用公共 + 大多數僅二進制的模塊是內核的派生產品，因此，它們的分發違反了GNU通用公共 許可證（下面將詳細介紹）。本文作者不是律師，本文檔中的任何內容都不可能被 - 視爲法律建議。封閉原始碼模塊的真實法律地位只能由法院決定。但不管怎樣，困擾 + 視爲法律建議。封閉源代碼模塊的真實法律地位只能由法院決定。但不管怎樣，困擾 這些模塊的不確定性仍然存在。 -- 二進位模塊大大增加了調試內核問題的難度，以至於大多數內核開發人員甚至都不會 - 嘗試。因此，只分發二進位模塊將使您的用戶更難從社區獲得支持。 +- 二進制模塊大大增加了調試內核問題的難度，以至於大多數內核開發人員甚至都不會 + 嘗試。因此，只分發二進制模塊將使您的用戶更難從社區獲得支持。 -- 對於僅二進位的模塊的發行者來說，支持也更加困難，他們必須爲他們希望支持的 +- 對於僅二進制的模塊的發行者來說，支持也更加困難，他們必須爲他們希望支持的 每個發行版和每個內核版本提供不同版本的模塊。爲了提供較爲全面的覆蓋範圍， 可能需要一個模塊的幾十個構建，並且每次升級內核時，您的用戶都必須單獨升級 這些模塊。 -- 上面提到的關於代碼評審的所有問題都更加存在於封閉原始碼中。由於該代碼根本 +- 上面提到的關於代碼評審的所有問題都更加存在於封閉源代碼中。由於該代碼根本 不可得，因此社區無法對其進行審查，毫無疑問，它將存在嚴重問題。 尤其是嵌入式系統的製造商，可能會傾向於忽視本節中所說的大部分內容；因爲他們 -相信自己正在商用一種使用凍結內核版本的獨立產品，在發布後不需要再進行開發。 +相信自己正在商用一種使用凍結內核版本的獨立產品，在發佈後不需要再進行開發。 這個論點忽略了廣泛的代碼審查的價值以及允許用戶向產品添加功能的價值。但這些 -產品的商業壽命有限，之後必須發布新版本的產品。在這一點上，代碼在主線上並得到 -良好維護的供應商將能夠更好地占位，以使新產品快速上市。 +產品的商業壽命有限，之後必須發佈新版本的產品。在這一點上，代碼在主線上並得到 +良好維護的供應商將能夠更好地佔位，以使新產品快速上市。 許可 ---- 代碼是根據一些許可證提供給Linux內核的，但是所有代碼都必須與GNU通用公共許可 證（GPLV2）的版本2兼容，該版本是覆蓋整個內核分發的許可證。在實踐中，這意味 -著所有代碼貢獻都由GPLv2（可選地，語言允許在更高版本的GPL下分發）或3子句BSD +着所有代碼貢獻都由GPLv2（可選地，語言允許在更高版本的GPL下分發）或3子句BSD 許可（New BSD License，譯者注）覆蓋。任何不包含在兼容許可證中的貢獻都不會 被接受到內核中。 貢獻給內核的代碼不需要（或請求）版權分配。合併到主線內核中的所有代碼都保留 其原始所有權；因此，內核現在擁有數千個所有者。 -這種所有權結構也暗示著，任何改變內核許可的嘗試都註定會失敗。很少有實際情況 +這種所有權結構也暗示着，任何改變內核許可的嘗試都註定會失敗。很少有實際情況 可以獲得所有版權所有者的同意（或者從內核中刪除他們的代碼）。因此，尤其是在 可預見的將來，許可證不大可能遷移到GPL的版本3。 -所有貢獻給內核的代碼都必須是合法的免費軟體。因此，不接受匿名（或化名）貢獻 -者的代碼。所有貢獻者都需要在他們的代碼上「sign off（簽發）」，聲明代碼可以 -在GPL下與內核一起分發。無法提供未被其所有者許可爲免費軟體的代碼，或可能爲 +所有貢獻給內核的代碼都必須是合法的免費軟件。因此，不接受匿名（或化名）貢獻 +者的代碼。所有貢獻者都需要在他們的代碼上“sign off（簽發）”，聲明代碼可以 +在GPL下與內核一起分發。無法提供未被其所有者許可爲免費軟件的代碼，或可能爲 內核造成版權相關問題的代碼（例如，由缺乏適當保護的反向工程工作派生的代碼） 不能被接受。 有關版權問題的提問在Linux開發郵件列表中很常見。這樣的問題通常會得到不少答案， -但請記住，回答這些問題的人不是律師，不能提供法律諮詢。如果您有關於Linux原始碼 -的法律問題，沒有什麼可以代替諮詢了解這一領域的律師。依賴從技術郵件列表中獲得 +但請記住，回答這些問題的人不是律師，不能提供法律諮詢。如果您有關於Linux源代碼 +的法律問題，沒有什麼可以代替諮詢瞭解這一領域的律師。依賴從技術郵件列表中獲得 的答案是一件冒險的事情。 diff --git a/Documentation/translations/zh_TW/process/2.Process.rst b/Documentation/translations/zh_TW/process/2.Process.rst index 9d465df1f6c3..f25dd2e62247 100644 --- a/Documentation/translations/zh_TW/process/2.Process.rst +++ b/Documentation/translations/zh_TW/process/2.Process.rst @@ -26,8 +26,8 @@ 總覽 ---- -內核開發人員使用一個鬆散的基於時間的發布過程，每兩到三個月發布一次新的主要 -內核版本。最近的發布歷史記錄如下： +內核開發人員使用一個鬆散的基於時間的發佈過程，每兩到三個月發佈一次新的主要 +內核版本。最近的發佈歷史記錄如下： ====== ================= 5.0 2019年3月3日 @@ -42,33 +42,33 @@ 版本包含大約13000個變更集，變更了幾十萬行代碼。因此，5.x是Linux內核開發的前 沿；內核使用滾動開發模型，不斷集成重大變化。 -對於每個版本的補丁合併，遵循一個相對簡單的規則。在每個開發周期的開頭，「合併 -窗口」被打開。這時，被認爲足夠穩定（並且被開發社區接受）的代碼被合併到主線內 -核中。在這段時間內，新開發周期的大部分變更（以及所有主要變更）將以接近每天 -1000次變更（「補丁」或「變更集」）的速度合併。 +對於每個版本的補丁合併，遵循一個相對簡單的規則。在每個開發週期的開頭，“合併 +窗口”被打開。這時，被認爲足夠穩定（並且被開發社區接受）的代碼被合併到主線內 +核中。在這段時間內，新開發週期的大部分變更（以及所有主要變更）將以接近每天 +1000次變更（“補丁”或“變更集”）的速度合併。 （順便說一句，值得注意的是，合併窗口期間集成的更改並不是憑空產生的；它們是經 提前收集、測試和分級的。稍後將詳細描述該過程的工作方式。） -合併窗口持續大約兩周。在這段時間結束時，LinusTorvalds將聲明窗口已關閉，並 -釋放第一個「rc」內核。例如，對於目標爲5.6的內核，在合併窗口結束時發生的釋放 +合併窗口持續大約兩週。在這段時間結束時，Linus Torvalds將聲明窗口已關閉，並 +釋放第一個“rc”內核。例如，對於目標爲5.6的內核，在合併窗口結束時發生的釋放 將被稱爲5.6-rc1。-rc1 版本是一個信號，表示合併新特性的時間已經過去，穩定下一 個內核的時間已經到來。 在接下來的6到10周內，只有修復問題的補丁才應該提交給主線。有時會允許更大的 更改，但這種情況很少發生；試圖在合併窗口外合併新功能的開發人員往往受不到 友好的接待。一般來說，如果您錯過了給定特性的合併窗口，最好的做法是等待下一 -個開發周期。（偶爾會對未支持硬體的驅動程序進行例外；如果它們不改變已有代碼， -則不會導致回歸，應該可以隨時被安全地加入）。 +個開發週期。（偶爾會對未支持硬件的驅動程序進行例外；如果它們不改變已有代碼， +則不會導致迴歸，應該可以隨時被安全地加入）。 -隨著修復程序進入主線，補丁速度將隨著時間的推移而變慢。Linus大約每周發布一次 -新的-rc內核；在內核被認爲足夠穩定並最終發布前，一般會達到-rc6到-rc9之間。 +隨着修復程序進入主線，補丁速度將隨着時間的推移而變慢。Linus大約每週發佈一次 +新的-rc內核；在內核被認爲足夠穩定並最終發佈前，一般會達到-rc6到-rc9之間。 然後，整個過程又重新開始了。 -例如，這裡是5.4的開發周期進行情況（2019年）: +例如，這裏是5.4的開發週期進行情況（2019年）: ============== ============================== - 九月 15 5.3 穩定版發布 + 九月 15 5.3 穩定版發佈 九月 30 5.4-rc1 合併窗口關閉 十月 6 5.4-rc2 十月 13 5.4-rc3 @@ -77,26 +77,26 @@ 十一月 3 5.4-rc6 十一月 10 5.4-rc7 十一月 17 5.4-rc8 - 十一月 24 5.4 穩定版發布 + 十一月 24 5.4 穩定版發佈 ============== ============================== -開發人員如何決定何時結束開發周期並創建穩定版本？最重要的指標是以前版本的 -回歸列表。不歡迎出現任何錯誤，但是那些破壞了以前能工作的系統的錯誤被認爲是 -特別嚴重的。因此，導致回歸的補丁是不受歡迎的，很可能在穩定期內刪除。 +開發人員如何決定何時結束開發週期並創建穩定版本？最重要的指標是以前版本的 +迴歸列表。不歡迎出現任何錯誤，但是那些破壞了以前能工作的系統的錯誤被認爲是 +特別嚴重的。因此，導致迴歸的補丁是不受歡迎的，很可能在穩定期內刪除。 -開發人員的目標是在穩定發布之前修復所有已知的回歸。在現實世界中，這種完美是 +開發人員的目標是在穩定發佈之前修復所有已知的迴歸。在現實世界中，這種完美是 很難實現的；在這種規模的項目中，變數太多了。需要說明的是，延遲最終版本只會 -使問題變得更糟；等待下一個合併窗口的更改將變多，導致下次出現更多的回歸錯誤。 -因此，大多數5.x內核都有一些已知的回歸錯誤，不過，希望沒有一個是嚴重的。 +使問題變得更糟；等待下一個合併窗口的更改將變多，導致下次出現更多的迴歸錯誤。 +因此，大多數5.x內核都有一些已知的迴歸錯誤，不過，希望沒有一個是嚴重的。 -一旦一個穩定的版本發布，它的持續維護工作就被移交給「穩定團隊」，目前由 -Greg Kroah-Hartman領導。穩定團隊將使用5.x.y編號方案不定期地發布穩定版本的 +一旦一個穩定的版本發佈，它的持續維護工作就被移交給“穩定團隊”，目前由 +Greg Kroah-Hartman領導。穩定團隊將使用5.x.y編號方案不定期地發佈穩定版本的 更新。要合入更新版本，補丁必須（1）修復一個重要的缺陷，且（2）已經合併到 -下一個開發版本主線中。內核通常會在其初始版本後的一個以上的開發周期內收到 +下一個開發版本主線中。內核通常會在其初始版本後的一個以上的開發週期內收到 穩定版更新。例如，5.2內核的歷史如下（2019年）： ============== =============================== - 七月 7 5.2 穩定版發布 + 七月 7 5.2 穩定版發佈 七月 13 5.2.1 七月 21 5.2.2 七月 26 5.2.3 @@ -108,7 +108,7 @@ Greg Kroah-Hartman領導。穩定團隊將使用5.x.y編號方案不定期地發 5.2.21是5.2版本的最終穩定更新。 -有些內核被指定爲「長期」內核；它們將得到更長時間的支持。在本文中，當前的長期 +有些內核被指定爲“長期”內核；它們將得到更長時間的支持。在本文中，當前的長期 內核及其維護者是： ====== ================================ ================ @@ -121,9 +121,9 @@ Greg Kroah-Hartman領導。穩定團隊將使用5.x.y編號方案不定期地發 ====== ================================ ================ 長期支持內核的選擇純粹是維護人員是否有需求和時間來維護該版本的問題。 -目前還沒有爲即將發布的任何特定版本提供長期支持的已知計劃。 +目前還沒有爲即將發佈的任何特定版本提供長期支持的已知計劃。 -補丁的生命周期 +補丁的生命週期 -------------- 補丁不會直接從開發人員的鍵盤進入主線內核。相反，有一個稍微複雜（如果有些非 @@ -140,7 +140,7 @@ Greg Kroah-Hartman領導。穩定團隊將使用5.x.y編號方案不定期地發 是在不涉及社區的情況下完成的，但是如果可能的話，最好是在公開的情況下完成 這項工作；這樣可以節省很多稍後再重新設計的時間。 -- 早期評審。補丁被發布到相關的郵件列表中，列表中的開發人員會回復他們可能有 +- 早期評審。補丁被髮布到相關的郵件列表中，列表中的開發人員會回覆他們可能有 的任何評論。如果一切順利的話，這個過程應該會發現補丁的任何主要問題。 - 更廣泛的評審。當補丁接近準備好納入主線時，它應該被相關的子系統維護人員 @@ -153,48 +153,48 @@ Greg Kroah-Hartman領導。穩定團隊將使用5.x.y編號方案不定期地發 如果您的補丁得到了需要更改的反饋，那麼您應該進行這些更改，或者解釋爲何 不應該進行這些更改。如果您的補丁沒有評審意見，也沒有被其相應的子系統或 驅動程序維護者接受，那麼您應該堅持不懈地將補丁更新到當前內核使其可被正常 - 應用，並不斷地發送它以供審查和合併。 + 應用，並不斷地發送它以供審查和合並。 - 合併到主線。最終，一個成功的補丁將被合併到由LinusTorvalds管理的主線存儲庫 中。此時可能會出現更多的評論和/或問題；對開發人員來說應對這些問題並解決 出現的任何問題仍很重要。 -- 穩定版發布。大量用戶可能受此補丁影響，因此可能再次出現新的問題。 +- 穩定版發佈。大量用戶可能受此補丁影響，因此可能再次出現新的問題。 - 長期維護。雖然開發人員在合併代碼後可能會忘記代碼，但這種行爲往往會給開發 社區留下不良印象。合併代碼消除了一些維護負擔，因爲其他人將修復由API更改 引起的問題。但是，如果代碼要長期保持可用，原始開發人員應該繼續爲代碼負責。 -內核開發人員（或他們的僱主）犯的最大錯誤之一是試圖將流程簡化爲一個「合併到 -主線」步驟。這種方法總是會讓所有相關人員感到沮喪。 +內核開發人員（或他們的僱主）犯的最大錯誤之一是試圖將流程簡化爲一個“合併到 +主線”步驟。這種方法總是會讓所有相關人員感到沮喪。 補丁如何進入內核 ---------------- -只有一個人可以將補丁合併到主線內核存儲庫中：LinusTorvalds。但是，在進入 +只有一個人可以將補丁合併到主線內核存儲庫中：Linus Torvalds。但是，在進入 2.6.38內核的9500多個補丁中，只有112個（大約1.3%）是由Linus自己直接選擇的。 內核項目已經發展到一個沒有一個開發人員可以在沒有支持的情況下檢查和選擇每個 補丁的規模。內核開發人員處理這種增長的方式是使用圍繞信任鏈構建的助理系統。 內核代碼庫在邏輯上被分解爲一組子系統：網絡、特定體系結構支持、內存管理、視 頻設備等。大多數子系統都有一個指定的維護人員，其總體負責該子系統中的代碼。 -這些子系統維護者（鬆散地）是他們所管理的內核部分的「守門員」；他們（通常） +這些子系統維護者（鬆散地）是他們所管理的內核部分的“守門員”；他們（通常） 會接受一個補丁以包含到主線內核中。 -子系統維護人員每個人都管理著自己版本的內核原始碼樹，通常（並非總是）使用Git。 +子系統維護人員每個人都管理着自己版本的內核源代碼樹，通常（並非總是）使用Git。 Git等工具（以及Quilt或Mercurial等相關工具）允許維護人員跟蹤補丁列表，包括作者 信息和其他元數據。在任何給定的時間，維護人員都可以確定他或她的存儲庫中的哪 些補丁在主線中找不到。 -當合併窗口打開時，頂級維護人員將要求Linus從存儲庫中「拉出」他們爲合併選擇 +當合並窗口打開時，頂級維護人員將要求Linus從存儲庫中“拉出”他們爲合併選擇 的補丁。如果Linus同意，補丁流將流向他的存儲庫，成爲主線內核的一部分。 Linus對拉取中接收到的特定補丁的關注程度各不相同。很明顯，有時他看起來很 -關注。但是一般來說，Linus相信子系統維護人員不會向上游發送壞補丁。 +關注。但是一般來說，Linus相信子系統維護人員不會向上遊發送壞補丁。 -子系統維護人員反過來也可以從其他維護人員那裡獲取補丁。例如，網絡樹是由首先 +子系統維護人員反過來也可以從其他維護人員那裏獲取補丁。例如，網絡樹是由首先 在專用於網絡設備驅動程序、無線網絡等的樹中積累的補丁構建的。此存儲鏈可以 -任意長，但很少超過兩個或三個連結。由於鏈中的每個維護者都信任那些管理較低 -級別樹的維護者，所以這個過程稱爲「信任鏈」。 +任意長，但很少超過兩個或三個鏈接。由於鏈中的每個維護者都信任那些管理較低 +級別樹的維護者，所以這個過程稱爲“信任鏈”。 顯然，在這樣的系統中，獲取內核補丁取決於找到正確的維護者。直接向Linus發送 補丁通常不是正確的方法。 @@ -204,30 +204,30 @@ Next 樹 子系統樹鏈引導補丁流到內核，但它也提出了一個有趣的問題：如果有人想查看爲 下一個合併窗口準備的所有補丁怎麼辦？開發人員將感興趣的是，還有什麼其他的 -更改有待解決，以了解是否存在需要擔心的衝突；例如，更改核心內核函數原型的 +更改有待解決，以瞭解是否存在需要擔心的衝突；例如，更改核心內核函數原型的 修補程序將與使用該函數舊形式的任何其他修補程序衝突。審查人員和測試人員希望 在所有這些變更到達主線內核之前，能夠訪問它們的集成形式的變更。您可以從所有 相關的子系統樹中提取更改，但這將是一項複雜且容易出錯的工作。 -解決方案以-next樹的形式出現，在這裡子系統樹被收集以供測試和審查。這些樹中 -由Andrew Morton維護的較老的一個，被稱爲「-mm」（用於內存管理，創建時爲此）。 +解決方案以-next樹的形式出現，在這裏子系統樹被收集以供測試和審查。這些樹中 +由Andrew Morton維護的較老的一個，被稱爲“-mm”（用於內存管理，創建時爲此）。 -mm 樹集成了一長串子系統樹中的補丁；它還包含一些旨在幫助調試的補丁。 除此之外，-mm 還包含大量由Andrew直接選擇的補丁。這些補丁可能已經發布在郵件 列表上，或者它們可能應用於內核中未指定子系統樹的部分。同時，-mm 作爲最後 手段的子系統樹；如果沒有其他明顯的路徑可以讓補丁進入主線，那麼它很可能最 終選擇-mm 樹。累積在-mm 中的各種補丁最終將被轉發到適當的子系統樹，或者直接 -發送到Linus。在典型的開發周期中，大約5-10%的補丁通過-mm 進入主線。 +發送到Linus。在典型的開發週期中，大約5-10%的補丁通過-mm 進入主線。 -當前-mm 補丁可在「mmotm」（-mm of the moment）目錄中找到： +當前-mm 補丁可在“mmotm”（-mm of the moment）目錄中找到： https://www.ozlabs.org/~akpm/mmotm/ 然而，使用MMOTM樹可能會十分令人頭疼；它甚至可能無法編譯。 -下一個周期補丁合併的主要樹是linux-next，由Stephen Rothwell 維護。根據設計 +下一個週期補丁合併的主要樹是linux-next，由Stephen Rothwell 維護。根據設計 linux-next 是下一個合併窗口關閉後主線的快照。linux-next樹在Linux-kernel 和 -Linux-next 郵件列表中發布，可從以下位置下載： +Linux-next 郵件列表中發佈，可從以下位置下載： https://www.kernel.org/pub/linux/kernel/next/ @@ -237,7 +237,7 @@ Linux-next 已經成爲內核開發過程中不可或缺的一部分；在一個 Staging 樹 ---------- -內核原始碼樹包含drivers/staging/目錄，其中有許多驅動程序或文件系統的子目錄 +內核源代碼樹包含drivers/staging/目錄，其中有許多驅動程序或文件系統的子目錄 正在被添加到內核樹中。它們在仍然需要更多的修正的時候可以保留在driver/staging/ 目錄中；一旦完成，就可以將它們移到內核中。這是一種跟蹤不符合Linux內核編碼或 質量標準的驅動程序的方法，人們可能希望使用它們並跟蹤開發。 @@ -251,7 +251,7 @@ Greg Kroah Hartman 目前負責維護staging 樹。仍需要修正的驅動程 Staging 是一種讓新的驅動程序進入主線的相對容易的方法，它們會幸運地引起其他 開發人員的注意，並迅速改進。然而，進入staging並不是故事的結尾；staging中 沒有看到常規進展的代碼最終將被刪除。經銷商也傾向於相對不願意使用staging驅動 -程序。因此，在成爲一個合適的主線驅動的路上，staging 僅是一個中轉站。 +程序。因此，在成爲一個合適的主線驅動的路上，staging 僅是一箇中轉站。 工具 ---- @@ -260,9 +260,9 @@ Staging 是一種讓新的驅動程序進入主線的相對容易的方法，它 能力。如果沒有適當強大的工具，整個系統將無法在任何地方正常工作。關於如何使用 這些工具的教程遠遠超出了本文檔的範圍，但還是用一點篇幅介紹一些關鍵點。 -到目前爲止，內核社區使用的主要原始碼管理系統是git。Git是在自由軟體社區中開發 -的許多分布式版本控制系統之一。它非常適合內核開發，因爲它在處理大型存儲庫和 -大量補丁時性能非常好。它也以難以學習和使用而著稱，儘管隨著時間的推移它變得 +到目前爲止，內核社區使用的主要源代碼管理系統是git。Git是在自由軟件社區中開發 +的許多分佈式版本控制系統之一。它非常適合內核開發，因爲它在處理大型存儲庫和 +大量補丁時性能非常好。它也以難以學習和使用而著稱，儘管隨着時間的推移它變得 更好了。對於內核開發人員來說，對Git的某種熟悉幾乎是一種要求；即使他們不將它 用於自己的工作，他們也需要Git來跟上其他開發人員（以及主線）正在做的事情。 @@ -270,7 +270,7 @@ Staging 是一種讓新的驅動程序進入主線的相對容易的方法，它 https://git-scm.com/ -此頁面包含了文檔和教程的連結。 +此頁面包含了文檔和教程的鏈接。 在不使用git的內核開發人員中，最流行的選擇幾乎肯定是Mercurial： @@ -282,16 +282,16 @@ Mercurial與Git共享許多特性，但它提供了一個界面，許多人覺 https://savannah.nongnu.org/projects/quilt -Quilt 是一個補丁管理系統，而不是原始碼管理系統。它不會隨著時間的推移跟蹤歷史； +Quilt 是一個補丁管理系統，而不是源代碼管理系統。它不會隨着時間的推移跟蹤歷史； 相反，它面向根據不斷發展的代碼庫跟蹤一組特定的更改。一些主要的子系統維護人員 -使用Quilt來管理打算向上游移動的補丁。對於某些樹的管理（例如-mm），quilt 是 +使用Quilt來管理打算向上遊移動的補丁。對於某些樹的管理（例如-mm），quilt 是 最好的工具。 郵件列表 -------- 大量的Linux內核開發工作是通過郵件列表完成的。如果不加入至少一個某個列表， -就很難成爲社區中的一個「全功能」成員。但是，Linux郵件列表對開發人員來說也是 +就很難成爲社區中的一個“全功能”成員。但是，Linux郵件列表對開發人員來說也是 一個潛在的危險，他們可能會被一堆電子郵件淹沒、違反Linux列表上使用的約定， 或者兩者兼而有之。 @@ -316,14 +316,14 @@ redhat.com/mailman/listinfo。 - 不要回復挑事的人。如果有人試圖激起憤怒，請忽略他們。 -- 當回復Linux內核電子郵件（或其他列表上的電子郵件）時，請爲所有相關人員保留 +- 當回覆Linux內核電子郵件（或其他列表上的電子郵件）時，請爲所有相關人員保留 Cc: 抄送頭。如果沒有確實的理由（如明確的請求），則不應刪除收件人。一定要 確保你要回復的人在抄送列表中。這個慣例也使你不必在回覆郵件時明確要求被抄送。 - 在提出問題之前，搜索列表存檔（和整個網絡）。有些開發人員可能會對那些顯然 沒有完成家庭作業的人感到不耐煩。 -- 避免頂部回復（把你的答案放在你要回復的引文上面的做法）。這會讓你的回答更難 +- 避免頂部回覆（把你的答案放在你要回復的引文上面的做法）。這會讓你的回答更難 理解，印象也很差。 - 在正確的郵件列表發問。linux-kernel 可能是通用的討論場所，但它不是尋找所有 @@ -332,7 +332,7 @@ redhat.com/mailman/listinfo。 最後一點——找到正確的郵件列表——是開發人員常出錯的地方。在linux-kernel上 提出與網絡相關的問題的人幾乎肯定會收到一個禮貌的建議，轉到netdev列表上提出， 因爲這是大多數網絡開發人員經常出現的列表。還有其他列表可用於scsi、video4linux、 -ide、filesystem等子系統。查找郵件列表的最佳位置是與內核原始碼一起打包的 +ide、filesystem等子系統。查找郵件列表的最佳位置是與內核源代碼一起打包的 MAINTAINERS文件。 開始內核開發 @@ -344,7 +344,7 @@ MAINTAINERS文件。 公司通常希望聘請知名的開發人員來啓動開發團隊。實際上，這是一種有效的技術。 但它也往往是昂貴的，而且對增加有經驗的內核開發人員的數量沒有多大幫助。考 慮到時間投入，可以讓內部開發人員加快Linux內核的開發速度。利用這段時間可以 -讓僱主擁有一批既了解內核又了解公司的開發人員，還可以幫助培訓其他人。從中期 +讓僱主擁有一批既瞭解內核又瞭解公司的開發人員，還可以幫助培訓其他人。從中期 來看，這通常是更有利可圖的方法。 可以理解的是，單個開發人員往往對起步感到茫然。從一個大型項目開始可能會很 @@ -353,17 +353,17 @@ MAINTAINERS文件。 這會分散整個開發社區的注意力，因此，它們越來越被人不看重。希望向社區介紹 自己的新開發人員將無法通過這些方式獲得他們期待的反響。 -Andrew Morton 爲有抱負的內核開發人員提供了如下建議 +Andrew Morton 爲有抱負的內核開發人員提供瞭如下建議 :: - 所有內核開發者的第一個項目肯定應該是「確保內核在您可以操作的所有 - 機器上始終完美運行」。通常的方法是和其他人一起解決問題（這可能需 + 所有內核開發者的第一個項目肯定應該是“確保內核在您可以操作的所有 + 機器上始終完美運行”。通常的方法是和其他人一起解決問題（這可能需 要堅持！），但就是如此——這是內核開發的一部分。 (http://lwn.net/Articles/283982/) -在沒有明顯問題需要解決的情況下，通常建議開發人員查看當前的回歸和開放缺陷 +在沒有明顯問題需要解決的情況下，通常建議開發人員查看當前的迴歸和開放缺陷 列表。從來都不缺少需要解決的問題；通過解決這些問題，開發人員將從該過程獲得 經驗，同時與開發社區的其他成員建立相互尊重。 diff --git a/Documentation/translations/zh_TW/process/3.Early-stage.rst b/Documentation/translations/zh_TW/process/3.Early-stage.rst index 076873ca0905..12ca5ed0c510 100644 --- a/Documentation/translations/zh_TW/process/3.Early-stage.rst +++ b/Documentation/translations/zh_TW/process/3.Early-stage.rst @@ -26,13 +26,13 @@ -------- 與任何工程項目一樣，成功的內核改善從清晰描述要解決的問題開始。在某些情況 -下，這個步驟很容易：例如當某個特定硬體需要驅動程序時。不過，在其他情況下， +下，這個步驟很容易：例如當某個特定硬件需要驅動程序時。不過，在其他情況下， 很容易將實際問題與建議的解決方案混在一起，這可能會導致麻煩。 -舉個例子：幾年前，Linux音頻的開發人員尋求一種方法來運行應用程式，而不會因 +舉個例子：幾年前，Linux音頻的開發人員尋求一種方法來運行應用程序，而不會因 系統延遲過大而導致退出或其他問題。他們得到的解決方案是一個連接到Linux安全 -模塊（LSM）框架中的內核模塊；這個模塊可以配置爲允許特定的應用程式訪問實時 -調度程序。這個模塊被實現並發到linux-kernel郵件列表，在那裡它立即遇到了麻煩。 +模塊（LSM）框架中的內核模塊；這個模塊可以配置爲允許特定的應用程序訪問實時 +調度程序。這個模塊被實現併發到linux-kernel郵件列表，在那裏它立即遇到了麻煩。 對於音頻開發人員來說，這個安全模塊足以解決他們當前的問題。但是，對於更廣泛的 內核社區來說，這被視爲對LSM框架的濫用（LSM框架並不打算授予他們原本不具備的 @@ -41,15 +41,15 @@ 然而，音頻社區無法超越他們實施的特定解決方案來看問題；他們不願意接受替代方案。 由此產生的分歧使這些開發人員對整個內核開發過程感到失望；其中一個開發人員返回 -到audio列表並發布了以下內容： +到audio列表併發布了以下內容： 有很多非常好的Linux內核開發人員，但他們往往會被一羣傲慢的傻瓜所壓倒。 - 試圖向這些人傳達用戶需求是浪費時間。他們太「聰明」了，根本聽不到少數 + 試圖向這些人傳達用戶需求是浪費時間。他們太“聰明”了，根本聽不到少數 人的話。 （http://lwn.net/Articles/131776/） -實際情況卻是不同的；與特定模塊相比，內核開發人員更關心系統穩定性、長期維護 +實際情況卻是不同的；與特定模塊相比，內核開發人員更關心繫統穩定性、長期維護 以及找到問題的正確解決方案。這個故事的寓意是把重點放在問題上——而不是具體的 解決方案上——並在開始編寫代碼之前與開發社區討論這個問題。 @@ -72,7 +72,7 @@ - 很可能問題是由內核以您不理解的方式解決的。Linux內核很大，具有許多不明顯 的特性和功能。並不是所有的內核功能都像人們所希望的那樣有文檔記錄，而且很 - 容易遺漏一些東西。某作者發布了一個完整的驅動程序，重複了一個其不 + 容易遺漏一些東西。某作者發佈了一個完整的驅動程序，重複了一個其不 知道的現有驅動程序。重新發明現有輪子的代碼不僅浪費，而且不會被接受到主線 內核中。 @@ -83,7 +83,7 @@ 可能願意幫助創建這個解決方案。 在內核開發社區的多年經驗給了我們一個明確的教訓：閉門設計和開發的內核代碼總是 -有一些問題，這些問題只有在代碼發布到社區中時才會被發現。有時這些問題很嚴重， +有一些問題，這些問題只有在代碼發佈到社區中時纔會被發現。有時這些問題很嚴重， 需要數月或數年的努力才能使代碼達到內核社區的標準。例如： - 設計並實現了單處理器系統的DeviceScape網絡棧。只有使其適合於多處理器系統， @@ -103,16 +103,16 @@ 找誰交流？ ---------- -當開發人員決定公開他們的計劃時，下一個問題是：我們從哪裡開始？答案是找到正確 +當開發人員決定公開他們的計劃時，下一個問題是：我們從哪裏開始？答案是找到正確 的郵件列表和正確的維護者。對於郵件列表，最好的方法是在維護者(MAINTAINERS)文件 -中查找要發布的相關位置。如果有一個合適的子系統列表，那麼其上發布通常比在 -linux-kernel上發布更可取；您更有可能接觸到在相關子系統中具有專業知識的開發 +中查找要發佈的相關位置。如果有一個合適的子系統列表，那麼其上發佈通常比在 +linux-kernel上發佈更可取；您更有可能接觸到在相關子系統中具有專業知識的開發 人員，並且環境可能具支持性。 找到維護人員可能會有點困難。同樣，維護者文件是開始的地方。但是，該文件往往不 -是最新的，並且並非所有子系統都在那裡顯示。實際上，維護者文件中列出的人員可能 +是最新的，並且並非所有子系統都在那裏顯示。實際上，維護者文件中列出的人員可能 不是當前實際擔任該角色的人員。因此，當對聯繫誰有疑問時，一個有用的技巧是使用 -git（尤其是「git-log」）查看感興趣的子系統中當前活動的用戶。看看誰在寫補丁、 +git（尤其是“git-log”）查看感興趣的子系統中當前活動的用戶。看看誰在寫補丁、 誰會在這些補丁上加上Signed-off-by行簽名（如有）。這些人將是幫助新開發項目的 最佳人選。 @@ -123,7 +123,7 @@ git（尤其是「git-log」）查看感興趣的子系統中當前活動的用 .../scripts/get_maintainer.pl -當給定「-f」選項時，此腳本將返回指定文件或目錄的當前維護者。如果在命令行上 +當給定“-f”選項時，此腳本將返回指定文件或目錄的當前維護者。如果在命令行上 給出了一個補丁，它將列出可能接收補丁副本的維護人員。有許多選項可以調節 get_maintainer.pl搜索維護者的嚴格程度；請小心使用更激進的選項，因爲最終結果 可能會包括對您正在修改的代碼沒有真正興趣的開發人員。 @@ -134,17 +134,17 @@ get_maintainer.pl搜索維護者的嚴格程度；請小心使用更激進的選 何時郵寄？ ---------- -如果可能的話，在早期階段發布你的計劃只會更有幫助。描述正在解決的問題以及已經 +如果可能的話，在早期階段發佈你的計劃只會更有幫助。描述正在解決的問題以及已經 制定的關於如何實施的任何計劃。您可以提供的任何信息都可以幫助開發社區爲項目 提供有用的輸入。 在這個階段可能發生的一件令人沮喪的事情不是得到反對意見，而是很少或根本沒有 反饋。令人傷心的事實是：（1）內核開發人員往往很忙；（2）不缺少有宏偉計劃但 代碼（甚至代碼設想）很少的人去支持他們；（3）沒有人有義務審查或評論別人發表 -的想法。除此之外，高層級的設計常常隱藏著一些問題，這些問題只有在有人真正嘗試 -實現這些設計時才會被發現；因此，內核開發人員寧願看到代碼。 +的想法。除此之外，高層級的設計常常隱藏着一些問題，這些問題只有在有人真正嘗試 +實現這些設計時纔會被發現；因此，內核開發人員寧願看到代碼。 -如果發布請求評論（RFC）並沒得到什麼有用的評論，不要以爲這意味著無人對此項目 +如果發佈請求評論（RFC）並沒得到什麼有用的評論，不要以爲這意味着無人對此項目 有興趣，同時你也不能假設你的想法沒有問題。在這種情況下，最好的做法是繼續進 行，把你的進展隨時通知社區。 @@ -152,12 +152,12 @@ get_maintainer.pl搜索維護者的嚴格程度；請小心使用更激進的選 ----------------------- 如果您的工作是在公司環境中完成的，就像大多數Linux內核工作一樣；顯然，在您將 -公司的計劃或代碼發布到公共郵件列表之前，必須獲得有適當權利經理的許可。發布 -不確定是否兼容GPL的代碼尤其會帶來問題；公司的管理層和法律人員越早能夠就發布 +公司的計劃或代碼發佈到公共郵件列表之前，必須獲得有適當權利經理的許可。發佈 +不確定是否兼容GPL的代碼尤其會帶來問題；公司的管理層和法律人員越早能夠就發佈 內核開發項目達成一致，對參與的每個人都越好。 一些讀者可能會認爲他們的核心工作是爲了支持還沒有正式承認存在的產品。將僱主 -的計劃公布在公共郵件列表上可能不是一個可行的選擇。在這種情況下，有必要考慮 +的計劃公佈在公共郵件列表上可能不是一個可行的選擇。在這種情況下，有必要考慮 保密是否真的是必要的；通常不需要把開發計劃關在門內。 的確，有些情況下一家公司在開發過程的早期無法合法地披露其計劃。擁有經驗豐富 diff --git a/Documentation/translations/zh_TW/process/4.Coding.rst b/Documentation/translations/zh_TW/process/4.Coding.rst index 7fc0344ed16b..96b8c0bd8423 100644 --- a/Documentation/translations/zh_TW/process/4.Coding.rst +++ b/Documentation/translations/zh_TW/process/4.Coding.rst @@ -19,7 +19,7 @@ ====================== 雖然一個堅實的、面向社區的設計過程有很多值得說道的，但是任何內核開發項目工作 -的證明都反映在代碼中。它是將由其他開發人員檢查併合並（或不合併）到主線樹中 +的證明都反映在代碼中。它是將由其他開發人員檢查併合並（或不合並）到主線樹中 的代碼。所以這段代碼的質量決定了項目的最終成功。 本節將檢查編碼過程。我們將從內核開發人員常犯的幾種錯誤開始。然後重點將轉移 @@ -32,7 +32,7 @@ ******** 內核長期以來都有其標準的代碼風格，如 -:ref:`Documentation/translations/zh_TW/process/coding-style.rst ` +:ref:`Documentation/translations/zh_CN/process/coding-style.rst ` 中所述。在多數時候，該文檔中描述的準則至多被認爲是建議性的。因此，內核中存在 大量不符合代碼風格準則的代碼。這種代碼的存在會給內核開發人員帶來兩方面的危害。 @@ -42,7 +42,7 @@ 開發人員能夠快速理解其中的任何部分。所以再也經不起奇怪格式的代碼的折騰了。 內核的代碼風格偶爾會與僱主的強制風格發生衝突。在這種情況下，必須在代碼合併 -之前遵從內核代碼風格。將代碼放入內核意味著以多種方式放棄一定程度的控制權—— +之前遵從內核代碼風格。將代碼放入內核意味着以多種方式放棄一定程度的控制權—— 包括控制代碼樣式。 另一個危害是認爲已經在內核中的代碼迫切需要修復代碼樣式。開發者可能會開始編寫 @@ -70,21 +70,21 @@ 簡單點，先考慮一個調用時始終只有一個參數且總爲零的函數。我們可以保留這個參數， 以在需要使用它時提供的額外靈活性。不過，在那時實現了這個額外參數的代碼很有 可能以某種從未被注意到的微妙方式被破壞——因爲它從未被使用過。或者當需要額外 -的靈活性時，它並未以符合程式設計師當初期望的方式來實現。內核開發人員通常會提交 +的靈活性時，它並未以符合程序員當初期望的方式來實現。內核開發人員通常會提交 補丁來刪除未使用的參數；一般來說，一開始就不應該添加這些參數。 -隱藏硬體訪問的抽象層——通常爲了允許大量的驅動程序兼容多個作業系統——尤其不受 +隱藏硬件訪問的抽象層——通常爲了允許大量的驅動程序兼容多個操作系統——尤其不受 歡迎。這樣的層使代碼變得模糊，可能會造成性能損失；它們不屬於Linux內核。 另一方面，如果您發現自己從另一個內核子系統複製了大量的代碼，那麼是時候 -了解一下：是否需要將這些代碼中的部分提取到單獨的庫中，或者在更高的層次上 +瞭解一下：是否需要將這些代碼中的部分提取到單獨的庫中，或者在更高的層次上 實現這些功能。在整個內核中複製相同的代碼沒有價值。 #ifdef 和預處理 *************** -C預處理器似乎給一些C程式設計師帶來了強大的誘惑，他們認爲它是一種將大量靈活性加入 -原始碼中的方法。但是預處理器不是C，大量使用它會導致代碼對其他人來說更難閱讀， +C預處理器似乎給一些C程序員帶來了強大的誘惑，他們認爲它是一種將大量靈活性加入 +源代碼中的方法。但是預處理器不是C，大量使用它會導致代碼對其他人來說更難閱讀， 對編譯器來說更難檢查正確性。使用了大量預處理器幾乎總是代碼需要一些 清理工作的標誌。 @@ -100,23 +100,23 @@ C預處理器宏存在許多危險性，包括可能對具有副作用且沒有 內聯函數 ******** -不過，內聯函數本身也存在風險。程式設計師可以傾心於避免函數調用和用內聯函數填充源 +不過，內聯函數本身也存在風險。程序員可以傾心於避免函數調用和用內聯函數填充源 文件所固有的效率。然而，這些功能實際上會降低性能。因爲它們的代碼在每個調用站 -點都被複製一遍，所以最終會增加編譯內核的大小。此外，這也對處理器的內存緩存 +點都被複制一遍，所以最終會增加編譯內核的大小。此外，這也對處理器的內存緩存 造成壓力，從而大大降低執行速度。通常內聯函數應該非常小，而且相對較少。畢竟 函數調用的成本並不高；大量創建內聯函數是過早優化的典型例子。 -一般來說，內核程式設計師會自冒風險忽略緩存效果。在數據結構課程開頭中的經典 -時間/空間權衡通常不適用於當代硬體。空間 *就是* 時間，因爲一個大的程序比一個 +一般來說，內核程序員會自冒風險忽略緩存效果。在數據結構課程開頭中的經典 +時間/空間權衡通常不適用於當代硬件。空間 *就是* 時間，因爲一個大的程序比一個 更緊湊的程序運行得慢。 較新的編譯器越來越激進地決定一個給定函數是否應該內聯。因此，隨意放置使用 -「inline」關鍵字可能不僅僅是過度的，也可能是無用的。 +“inline”關鍵字可能不僅僅是過度的，也可能是無用的。 鎖 ** -2006年5月，「deviceescape」網絡堆棧在前呼後擁下以GPL發布，並被納入主線內核。 +2006年5月，“deviceescape”網絡堆棧在前呼後擁下以GPL發佈，並被納入主線內核。 這是一個受歡迎的消息；Linux中對無線網絡的支持充其量被認爲是不合格的，而 Deviceescape堆棧承諾修復這種情況。然而直到2007年6月（2.6.22），這段代碼才真 正進入主線。發生了什麼？ @@ -125,25 +125,25 @@ Deviceescape堆棧承諾修復這種情況。然而直到2007年6月（2.6.22） 設計。在合併這個網絡堆棧（現在稱爲mac80211）之前，需要對其進行一個鎖方案的 改造。 -曾經，Linux內核代碼可以在不考慮多處理器系統所帶來的並發性問題的情況下進行 +曾經，Linux內核代碼可以在不考慮多處理器系統所帶來的併發性問題的情況下進行 開發。然而現在，這個文檔就是在雙核筆記本電腦上寫的。即使在單處理器系統上， -爲提高響應能力所做的工作也會提高內核內的並發性水平。編寫內核代碼而不考慮鎖 +爲提高響應能力所做的工作也會提高內核內的併發性水平。編寫內核代碼而不考慮鎖 的日子早已遠去。 -可以由多個線程並發訪問的任何資源（數據結構、硬體寄存器等）必須由鎖保護。新 +可以由多個線程併發訪問的任何資源（數據結構、硬件寄存器等）必須由鎖保護。新 的代碼應該謹記這一要求；事後修改鎖是一項相當困難的任務。內核開發人員應該花 -時間充分了解可用的鎖原語，以便爲工作選擇正確的工具。對並發性缺乏關注的代碼 +時間充分了解可用的鎖原語，以便爲工作選擇正確的工具。對併發性缺乏關注的代碼 很難進入主線。 -回歸 +迴歸 **** -最後一個值得一提的危險是回歸：它可能會引起導致現有用戶的某些東西中斷的改變 -（這也可能會帶來很大的改進）。這種變化被稱爲「回歸」，回歸已經成爲主線內核 -最不受歡迎的問題。除了少數例外情況，如果回歸不能及時修正，會導致回歸的修改 -將被取消。最好首先避免回歸發生。 +最後一個值得一提的危險是迴歸：它可能會引起導致現有用戶的某些東西中斷的改變 +（這也可能會帶來很大的改進）。這種變化被稱爲“迴歸”，迴歸已經成爲主線內核 +最不受歡迎的問題。除了少數例外情況，如果迴歸不能及時修正，會導致迴歸的修改 +將被取消。最好首先避免迴歸發生。 -人們常常爭論，如果回歸帶來的功能遠超過產生的問題，那麼回歸是否爲可接受的。 +人們常常爭論，如果迴歸帶來的功能遠超過產生的問題，那麼迴歸是否爲可接受的。 如果它破壞了一個系統卻爲十個系統帶來新的功能，爲何不改改態度呢？2007年7月， Linus對這個問題給出了最佳答案: @@ -154,7 +154,7 @@ Linus對這個問題給出了最佳答案: （http://lwn.net/Articles/243460/） -特別不受歡迎的一種回歸類型是用戶空間ABI的任何變化。一旦接口被導出到用戶空間， +特別不受歡迎的一種迴歸類型是用戶空間ABI的任何變化。一旦接口被導出到用戶空間， 就必須無限期地支持它。這一事實使得用戶空間接口的創建特別具有挑戰性：因爲它們 不能以不兼容的方式進行更改，所以必須一次就對。因此，用戶空間接口總是需要大量 的思考、清晰的文檔和廣泛的審查。 @@ -171,19 +171,19 @@ Linus對這個問題給出了最佳答案: 第一步是注意編譯器產生的警告。當前版本的GCC可以檢測（並警告）大量潛在錯誤。 通常，這些警告都指向真正的問題。提交以供審閱的代碼一般不會產生任何編譯器警告。 -在消除警告時，注意了解真正的原因，並儘量避免僅「修復」使警告消失而不解決其原因。 +在消除警告時，注意瞭解真正的原因，並儘量避免僅“修復”使警告消失而不解決其原因。 -請注意，並非所有編譯器警告都默認啓用。使用「make KCFLAGS=-W」構建內核以 +請注意，並非所有編譯器警告都默認啓用。使用“make KCFLAGS=-W”構建內核以 獲得完整集合。 -內核提供了幾個配置選項，可以打開調試功能；大多數配置選項位於「kernel hacking」 +內核提供了幾個配置選項，可以打開調試功能；大多數配置選項位於“kernel hacking” 子菜單中。對於任何用於開發或測試目的的內核，都應該啓用其中幾個選項。特別是， 您應該打開： - FRAME_WARN 獲取大於給定數量的堆棧幀的警告。 這些警告生成的輸出可能比較冗長，但您不必擔心來自內核其他部分的警告。 - - DEBUG_OBJECTS 將添加代碼以跟蹤內核創建的各種對象的生命周期，並在出現問題 + - DEBUG_OBJECTS 將添加代碼以跟蹤內核創建的各種對象的生命週期，並在出現問題 時發出警告。如果你要添加創建（和導出）關於其自己的複雜對象的子系統，請 考慮打開對象調試基礎結構的支持。 @@ -195,34 +195,34 @@ Linus對這個問題給出了最佳答案: 還有很多其他調試選項，其中一些將在下面討論。其中一些有顯著的性能影響，不應 一直使用。在學習可用選項上花費一些時間，可能會在短期內得到許多回報。 -其中一個較重的調試工具是鎖檢查器或「lockdep」。該工具將跟蹤系統中每個鎖 +其中一個較重的調試工具是鎖檢查器或“lockdep”。該工具將跟蹤系統中每個鎖 （spinlock或mutex）的獲取和釋放、獲取鎖的相對順序、當前中斷環境等等。然後， 它可以確保總是以相同的順序獲取鎖，相同的中斷假設適用於所有情況等等。換句話 說，lockdep可以找到許多導致系統死鎖的場景。在部署的系統中，這種問題可能會 很痛苦（對於開發人員和用戶而言）；LockDep允許提前以自動方式發現問題。具有 -任何類型的非普通鎖的代碼在提交合併前應在啓用lockdep的情況下運行測試。 +任何類型的非普通鎖的代碼在提交合並前應在啓用lockdep的情況下運行測試。 -作爲一個勤奮的內核程式設計師，毫無疑問，您將檢查任何可能失敗的操作（如內存分配） +作爲一個勤奮的內核程序員，毫無疑問，您將檢查任何可能失敗的操作（如內存分配） 的返回狀態。然而，事實上，最終的故障復現路徑可能完全沒有經過測試。未測試的 代碼往往會出問題；如果所有這些錯誤處理路徑都被執行了幾次，那麼您可能對代碼 更有信心。 內核提供了一個可以做到這一點的錯誤注入框架，特別是在涉及內存分配的情況下。 啓用故障注入後，內存分配的可配置失敗的百分比；這些失敗可以限定在特定的代碼 -範圍內。在啓用了故障注入的情況下運行，程式設計師可以看到當情況惡化時代碼如何響 +範圍內。在啓用了故障注入的情況下運行，程序員可以看到當情況惡化時代碼如何響 應。有關如何使用此工具的詳細信息，請參閱 Documentation/fault-injection/fault-injection.rst。 -「sparse」靜態分析工具可以發現其他類型的錯誤。sparse可以警告程式設計師用戶空間 +“sparse”靜態分析工具可以發現其他類型的錯誤。sparse可以警告程序員用戶空間 和內核空間地址之間的混淆、大端序與小端序的混淆、在需要一組位標誌的地方傳遞 -整數值等等。sparse必須單獨安裝(如果您的分發伺服器沒有將其打包， +整數值等等。sparse必須單獨安裝(如果您的分發服務器沒有將其打包， 可以在 https://sparse.wiki.kernel.org/index.php/Main_page 找到）, -然後可以通過在make命令中添加「C=1」在代碼上運行它。 +然後可以通過在make命令中添加“C=1”在代碼上運行它。 -「Coccinelle」工具 :ref:`http://coccinelle.lip6.fr/ ` -能夠發現各種潛在的編碼問題；它還可以爲這些問題提出修複方案。在 -scripts/coccinelle目錄下已經打包了相當多的內核「語義補丁」；運行 -「make coccicheck」將運行這些語義補丁並報告發現的任何問題。有關詳細信息，請參閱 +“Coccinelle”工具 :ref:`http://coccinelle.lip6.fr/ ` +能夠發現各種潛在的編碼問題；它還可以爲這些問題提出修復方案。在 +scripts/coccinelle目錄下已經打包了相當多的內核“語義補丁”；運行 +“make coccicheck”將運行這些語義補丁並報告發現的任何問題。有關詳細信息，請參閱 :ref:`Documentation/dev-tools/coccinelle.rst ` @@ -247,7 +247,7 @@ scripts/coccinelle目錄下已經打包了相當多的內核「語義補丁」 任何添加新用戶空間接口的代碼——包括新的sysfs或/proc文件——都應該包含該接口 的文檔，該文檔使用戶空間開發人員能夠知道他們在使用什麼。請參閱 -Documentation/ABI/README，了解如何此文檔格式以及需要提供哪些信息。 +Documentation/ABI/README，瞭解如何此文檔格式以及需要提供哪些信息。 文檔 :ref:`Documentation/admin-guide/kernel-parameters.rst ` 描述了內核的所有引導時間參數。任何添加新參數的補丁都應該向該文檔添加適當的 @@ -256,27 +256,27 @@ Documentation/ABI/README，了解如何此文檔格式以及需要提供哪些 任何新的配置選項都必須附有幫助文本，幫助文本需清楚地解釋這些選項以及用戶可能 希望何時使用它們。 -許多子系統的內部API信息通過專門格式化的注釋進行記錄；這些注釋可以通過 -「kernel-doc」腳本以多種方式提取和格式化。如果您在具有kerneldoc注釋的子系統中 +許多子系統的內部API信息通過專門格式化的註釋進行記錄；這些註釋可以通過 +“kernel-doc”腳本以多種方式提取和格式化。如果您在具有kerneldoc註釋的子系統中 工作，則應該維護它們，並根據需要爲外部可用的功能添加它們。即使在沒有如此記錄 -的領域中，爲將來添加kerneldoc注釋也沒有壞處；實際上，這對於剛開始開發內核的人 -來說是一個有用的活動。這些注釋的格式以及如何創建kerneldoc模板的一些信息可以在 +的領域中，爲將來添加kerneldoc註釋也沒有壞處；實際上，這對於剛開始開發內核的人 +來說是一個有用的活動。這些註釋的格式以及如何創建kerneldoc模板的一些信息可以在 :ref:`Documentation/doc-guide/ ` 上找到。 -任何閱讀大量現有內核代碼的人都會注意到，注釋的缺失往往是最值得注意的。同時， -對新代碼的要求比過去更高；合併未注釋的代碼將更加困難。這就是說，人們並不期望 -詳細注釋的代碼。代碼本身應該是自解釋的，注釋闡釋了更微妙的方面。 +任何閱讀大量現有內核代碼的人都會注意到，註釋的缺失往往是最值得注意的。同時， +對新代碼的要求比過去更高；合併未註釋的代碼將更加困難。這就是說，人們並不期望 +詳細註釋的代碼。代碼本身應該是自解釋的，註釋闡釋了更微妙的方面。 -某些事情應該總是被注釋。使用內存屏障時，應附上一行文字，解釋爲什麼需要設置內存 +某些事情應該總是被註釋。使用內存屏障時，應附上一行文字，解釋爲什麼需要設置內存 屏障。數據結構的鎖規則通常需要在某個地方解釋。一般來說，主要數據結構需要全面 的文檔。應該指出代碼中分立的位之間不明顯的依賴性。任何可能誘使代碼管理人進行 -錯誤的「清理」的事情都需要一個注釋來說明爲什麼要這樣做。等等。 +錯誤的“清理”的事情都需要一個註釋來說明爲什麼要這樣做。等等。 內部API更改 ----------- -內核提供給用戶空間的二進位接口不能被破壞，除非逼不得已。而內核的內部編程接口 +內核提供給用戶空間的二進制接口不能被破壞，除非逼不得已。而內核的內部編程接口 是高度流動的，當需要時可以更改。如果你發現自己不得不處理一個內核API，或者僅 僅因爲它不滿足你的需求導致無法使用特定的功能，這可能是API需要改變的一個標誌。 作爲內核開發人員，您有權進行此類更改。 @@ -287,7 +287,7 @@ Documentation/ABI/README，了解如何此文檔格式以及需要提供哪些 另一個要點是，更改內部API的開發人員通常要負責修復內核樹中被更改破壞的任何代碼。 對於一個廣泛使用的函數，這個責任可以導致成百上千的變化，其中許多變化可能與其他 -開發人員正在做的工作相衝突。不用說，這可能是一項大工程，所以最好確保理由是 +開發人員正在做的工作相沖突。不用說，這可能是一項大工程，所以最好確保理由是 可靠的。請注意，coccinelle工具可以幫助進行廣泛的API更改。 在進行不兼容的API更改時，應儘可能確保編譯器捕獲未更新的代碼。這將幫助您確保找 diff --git a/Documentation/translations/zh_TW/process/5.Posting.rst b/Documentation/translations/zh_TW/process/5.Posting.rst index 280a8832ecc0..caef6e0b31a5 100644 --- a/Documentation/translations/zh_TW/process/5.Posting.rst +++ b/Documentation/translations/zh_TW/process/5.Posting.rst @@ -15,27 +15,27 @@ .. _tw_development_posting: -發布補丁 +發佈補丁 ======== 您的工作遲早會準備好提交給社區進行審查，並最終包含到主線內核中。毫不稀奇， -內核開發社區已經發展出一套用於發布補丁的約定和過程；遵循這些約定和過程將使 +內核開發社區已經發展出一套用於發佈補丁的約定和過程；遵循這些約定和過程將使 參與其中的每個人的生活更加輕鬆。本文檔試圖描述這些約定的部分細節；更多信息 也可在以下文檔中找到 -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst ` -和 :ref:`Documentation/translations/zh_TW/process/submit-checklist.rst `。 +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst ` +和 :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst `。 -何時郵寄 +何時寄送 -------- -在補丁完全「準備好」之前，避免發布補丁是一種持續的誘惑。對於簡單的補丁，這 +在補丁完全“準備好”之前，避免發佈補丁是一種持續的誘惑。對於簡單的補丁，這 不是問題。但是如果正在完成的工作很複雜，那麼在工作完成之前從社區獲得反饋就 -可以獲得很多好處。因此，您應該考慮發布正在進行的工作，甚至維護一個可用的Git +可以獲得很多好處。因此，您應該考慮發佈正在進行的工作，甚至維護一個可用的Git 樹，以便感興趣的開發人員可以隨時趕上您的工作。 -當發布中有尚未準備好被包含的代碼，最好在發布中說明。還應提及任何有待完成的 +當發佈中有尚未準備好被包含的代碼，最好在發佈中說明。還應提及任何有待完成的 主要工作和任何已知問題。很少有人會願意看那些被認爲是半生不熟的補丁，但是 -那些願意的人會帶著他們的點子來一起幫助你把工作推向正確的方向。 +那些願意的人會帶着他們的點子來一起幫助你把工作推向正確的方向。 創建補丁之前 ------------ @@ -50,20 +50,20 @@ - 您的更改是否具有性能影響？如果是這樣，您應該運行基準測試來顯示您的變更的 影響（或好處）；結果的摘要應該包含在補丁中。 - - 確保您有權發布代碼。如果這項工作是爲僱主完成的，僱主對這項工作具有所有權， - 並且必須同意根據GPL對其進行發布。 + - 確保您有權發佈代碼。如果這項工作是爲僱主完成的，僱主對這項工作具有所有權， + 並且必須同意根據GPL對其進行發佈。 -一般來說，在發布代碼之前進行一些額外的思考，幾乎總是能在短時間內得到回報。 +一般來說，在發佈代碼之前進行一些額外的思考，幾乎總是能在短時間內得到回報。 補丁準備 -------- -準備補丁發布的工作量可能很驚人，但在此嘗試節省時間通常是不明智的，即使在短期 +準備補丁發佈的工作量可能很驚人，但在此嘗試節省時間通常是不明智的，即使在短期 內亦然。 必須針對內核的特定版本準備補丁。一般來說，補丁應該基於Linus的Git樹中的當前 -主線。當以主線爲基礎時，請從一個衆所周知的發布點開始——如穩定版本或 -rc -版本發布點——而不是在一個任意的主線分支點。 +主線。當以主線爲基礎時，請從一個衆所周知的發佈點開始——如穩定版本或 -rc +版本發佈點——而不是在一個任意的主線分支點。 也可能需要針對-mm、linux-next或子系統樹生成版本，以便於更廣泛的測試和審查。 根據補丁的區域以及其他地方的情況，針對其他樹建立的補丁可能需要大量的工作來 @@ -73,12 +73,12 @@ 分割補丁是一門藝術；一些開發人員花了很長時間來弄清楚如何按照社區期望的方式來 分割。不過，這些經驗法則也許有幫助： - - 您發布的補丁系列幾乎肯定不會是開發過程中版本控制系統中的一系列更改。相反， + - 您發佈的補丁系列幾乎肯定不會是開發過程中版本控制系統中的一系列更改。相反， 需要對您所做更改的最終形式加以考慮，然後以有意義的方式進行拆分。開發人員對 離散的、自包含的更改感興趣，而不是您創造這些更改的原始路徑。 - - 每個邏輯上獨立的變更都應該格式化爲單獨的補丁。這些更改可以是小的（如「向 - 此結構體添加欄位」）或大的（如添加一個重要的新驅動程序），但它們在概念上 + - 每個邏輯上獨立的變更都應該格式化爲單獨的補丁。這些更改可以是小的（如“向 + 此結構體添加字段”）或大的（如添加一個重要的新驅動程序），但它們在概念上 應該是小的，並且可以在一行內簡述。每個補丁都應該做一個特定的、可以單獨 檢查並驗證它所做的事情的更改。 @@ -88,34 +88,34 @@ - 每個補丁都應該能創建一個可以正確地構建和運行的內核；如果補丁系列在中間被 斷開，那麼結果仍應是一個正常工作的內核。部分應用一系列補丁是使用 - 「git bisct」工具查找回歸的一個常見場景；如果結果是一個損壞的內核，那麼將使 + “git bisct”工具查找回歸的一個常見場景；如果結果是一個損壞的內核，那麼將使 那些從事追蹤問題的高尚工作的開發人員和用戶的生活更加艱難。 - 不要過分分割。一位開發人員曾經將一組針對單個文件的編輯分成500個單獨的補丁 - 發布，這並沒有使他成爲內核郵件列表中最受歡迎的人。一個補丁可以相當大， + 發佈，這並沒有使他成爲內核郵件列表中最受歡迎的人。一個補丁可以相當大， 只要它仍然包含一個單一的 *邏輯* 變更。 - 用一系列補丁添加一個全新的基礎設施，但是該設施在系列中的最後一個補丁啓用 整個變更之前不能使用，這看起來很誘人。如果可能的話，應該避免這種誘惑； - 如果這個系列增加了回歸，那麼二分法將指出最後一個補丁是導致問題的補丁， + 如果這個系列增加了迴歸，那麼二分法將指出最後一個補丁是導致問題的補丁， 即使真正的bug在其他地方。只要有可能，添加新代碼的補丁程序應該立即激活該 代碼。 -創建完美補丁系列的工作可能是一個令人沮喪的過程，在完成「真正的工作」之後需要 +創建完美補丁系列的工作可能是一個令人沮喪的過程，在完成“真正的工作”之後需要 花費大量的時間和思考。但是如果做得好，花費的時間就是值得的。 補丁格式和更改日誌 ------------------ -所以現在你有了一系列完美的補丁可以發布，但是這項工作還沒有完成。每個補丁都 +所以現在你有了一系列完美的補丁可以發佈，但是這項工作還沒有完成。每個補丁都 需要被格式化成一條消息，以快速而清晰地將其目的傳達到世界其他地方。爲此， 每個補丁將由以下部分組成： - - 可選的「From」行，表明補丁作者。只有當你通過電子郵件發送別人的補丁時，這一行 - 才是必須的，但是爲防止疑問加上它也不會有什麼壞處。 + - 可選的“From”行，表明補丁作者。只有當你通過電子郵件發送別人的補丁時，這一行 + 纔是必須的，但是爲防止疑問加上它也不會有什麼壞處。 - 一行描述，說明補丁的作用。對於在沒有其他上下文的情況下看到該消息的讀者來說， - 該消息應足以確定修補程序的範圍；此行將顯示在「short form（簡短格式）」變更 + 該消息應足以確定修補程序的範圍；此行將顯示在“short form（簡短格式）”變更 日誌中。此消息通常需要先加上子系統名稱前綴，然後是補丁的目的。例如： :: @@ -144,17 +144,17 @@ 一般來說，你越把自己放在每個閱讀你變更日誌的人的位置上，變更日誌（和內核 作爲一個整體）就越好。 -不消說，變更日誌是將變更提交到版本控制系統時使用的文本。接下來將是： +不需要說，變更日誌是將變更提交到版本控制系統時使用的文本。接下來將是： - - 補丁本身，採用統一的（「-u」）補丁格式。使用「-p」選項來diff將使函數名與 + - 補丁本身，採用統一的（“-u”）補丁格式。使用“-p”選項來diff將使函數名與 更改相關聯，從而使結果補丁更容易被其他人讀取。 您應該避免在補丁中包括與更改不相關文件（例如，構建過程生成的文件或編輯器 -備份文件）。文檔目錄中的「dontdiff」文件在這方面有幫助；使用「-X」選項將 +備份文件）。文檔目錄中的“dontdiff”文件在這方面有幫助；使用“-X”選項將 其傳遞給diff。 上面提到的標籤（tag）用於描述各種開發人員如何與這個補丁的開發相關聯。 -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst ` +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst ` 文檔中對它們進行了詳細描述；下面是一個簡短的總結。每一行的格式如下： :: @@ -165,14 +165,14 @@ - Signed-off-by: 這是一個開發人員的證明，證明他或她有權提交補丁以包含到內核 中。這表明同意開發者來源認證協議，其全文見 - :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst ` + :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst ` 如果沒有合適的簽字，則不能合併到主線中。 - Co-developed-by: 聲明補丁是由多個開發人員共同創建的；當幾個人在一個補丁上 工作時，它用於給出共同作者（除了 From: 所給出的作者之外）。由於 Co-developed-by: 表示作者身份，所以每個共同開發人，必須緊跟在相關合作作者 的Signed-off-by之後。具體內容和示例見以下文件 - :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst ` + :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst ` - Acked-by: 表示另一個開發人員（通常是相關代碼的維護人員）同意補丁適合包含 在內核中。 @@ -180,7 +180,7 @@ - Tested-by: 聲明某人已經測試了補丁並確認它可以工作。 - Reviewed-by: 表示某開發人員已經審查了補丁的正確性；有關詳細信息，請參閱 - :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst ` + :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst ` - Reported-by: 指定報告此補丁修復的問題的用戶；此標記用於表示感謝。 @@ -188,16 +188,16 @@ 在補丁中添加標籤時要小心：只有Cc:才適合在沒有指定人員明確許可的情況下添加。 -發送補丁 +寄送補丁 -------- -在寄出補丁之前，您還需要注意以下幾點： +在寄送補丁之前，您還需要注意以下幾點： - 您確定您的郵件發送程序不會損壞補丁嗎？被郵件客戶端更改空白或修飾了行的補丁 無法被另一端接受，並且通常不會進行任何詳細檢查。如果有任何疑問，先把補丁寄 給你自己，讓你自己確定它是完好無損的。 - :ref:`Documentation/translations/zh_TW/process/email-clients.rst ` + :ref:`Documentation/translations/zh_CN/process/email-clients.rst ` 提供了一些有用的提示，可以讓特定的郵件客戶端正常發送補丁。 - 你確定你的補丁沒有荒唐的錯誤嗎？您應該始終通過scripts/checkpatch.pl檢查 @@ -209,12 +209,12 @@ 引用補丁的部分。相反，只需將補丁直接放到您的消息中。 寄出補丁時，重要的是將副本發送給任何可能感興趣的人。與其他一些項目不同，內核 -鼓勵人們甚至錯誤地發送過多的副本；不要假定相關人員會看到您在郵件列表中的發布。 +鼓勵人們甚至錯誤地發送過多的副本；不要假定相關人員會看到您在郵件列表中的發佈。 尤其是，副本應發送至： - 受影響子系統的維護人員。如前所述，維護人員文件是查找這些人員的首選地方。 - - 其他在同一領域工作的開發人員，尤其是那些現在可能在那裡工作的開發人員。使用 + - 其他在同一領域工作的開發人員，尤其是那些現在可能在那裏工作的開發人員。使用 git查看還有誰修改了您正在處理的文件，這很有幫助。 - 如果您對某錯誤報告或功能請求做出響應，也可以抄送原始發送人。 @@ -223,7 +223,7 @@ - 如果您正在修復一個缺陷，請考慮該修復是否應進入下一個穩定更新。如果是這樣， 補丁副本也應發到stable@vger.kernel.org 。另外，在補丁本身的標籤中添加一個 - 「Cc: stable@vger.kernel.org」；這將使穩定版團隊在修復進入主線時收到通知。 + “Cc: stable@vger.kernel.org”；這將使穩定版團隊在修復進入主線時收到通知。 當爲一個補丁選擇接收者時，最好清楚你認爲誰最終會接受這個補丁並將其合併。雖然 可以將補丁直接發給Linus Torvalds並讓他合併，但通常情況下不會這樣做。Linus很 @@ -236,7 +236,7 @@ [PATCH nn/mm] subsys: one-line description of the patch -其中「nn」是補丁的序號，「mm」是系列中補丁的總數，「subsys」是受影響子系統的 +其中“nn”是補丁的序號，“mm”是系列中補丁的總數，“subsys”是受影響子系統的 名稱。當然，一個單獨的補丁可以省略nn/mm。 如果您有一系列重要的補丁，那麼通常發送一個簡介作爲第〇部分。不過，這個約定 diff --git a/Documentation/translations/zh_TW/process/6.Followthrough.rst b/Documentation/translations/zh_TW/process/6.Followthrough.rst index 4af782742db3..ba0ff4ae9d0e 100644 --- a/Documentation/translations/zh_TW/process/6.Followthrough.rst +++ b/Documentation/translations/zh_TW/process/6.Followthrough.rst @@ -18,13 +18,13 @@ 跟進 ==== -此時，您已經遵循了到目前爲止給出的指導方針，並且，隨著您自己的工程技能的增加， +此時，您已經遵循了到目前爲止給出的指導方針，並且，隨着您自己的工程技能的增加， 已經發布了一系列完美的補丁。即使是經驗豐富的內核開發人員也能犯的最大錯誤之一 -是，認爲他們的工作現在已經完成了。事實上，發布補丁意味著進入流程的下一個階段， +是，認爲他們的工作現在已經完成了。事實上，發佈補丁意味着進入流程的下一個階段， 可能還需要做很多工作。 -一個補丁在首次發布時就非常出色、沒有改進的餘地，這是很罕見的。內核開發流程已 -認識到這一事實，因此它非常注重對已發布代碼的改進。作爲代碼的作者，您應該與 +一個補丁在首次發佈時就非常出色、沒有改進的餘地，這是很罕見的。內核開發流程已 +認識到這一事實，因此它非常注重對已發佈代碼的改進。作爲代碼的作者，您應該與 內核社區合作，以確保您的代碼符合內核的質量標準。如果不參與這個過程，很可能會 無法將補丁合併到主線中。 @@ -41,7 +41,7 @@ 調整到大量的重寫——都來自於對Linux的理解，即從現在起十年後，Linux仍將 在開發中。 - - 代碼審查是一項艱苦的工作，這是一項相對吃力不討好的工作；人們記得誰編寫了 + - 代碼審查是一項艱苦的工作，這是一項相對喫力不討好的工作；人們記得誰編寫了 內核代碼，但對於那些審查它的人來說，幾乎沒有什麼長久的名聲。因此，審閱 人員可能會變得暴躁，尤其是當他們看到同樣的錯誤被一遍又一遍地犯下時。如果 你得到了一個看起來憤怒、侮辱或完全冒犯你的評論，請抑制以同樣方式回應的衝動。 @@ -54,7 +54,7 @@ 所有這些歸根結底就是，當審閱者向您發送評論時，您需要注意他們正在進行的技術 評論。不要讓他們的表達方式或你自己的驕傲阻止此事。當你在一個補丁上得到評論 -時，花點時間去理解評論人想說什麼。如果可能的話，請修覆審閱者要求您修復的內 +時，花點時間去理解評論人想說什麼。如果可能的話，請修復審閱者要求您修復的內 容。然後回覆審閱者：謝謝他們，並描述你將如何回答他們的問題。 請注意，您不必同意審閱者建議的每個更改。如果您認爲審閱者誤解了您的代碼，請 @@ -65,19 +65,19 @@ 是錯誤的，或者你甚至沒有解決正確的問題。 Andrew Morton建議，每一個不會導致代碼更改的審閱評論都應該產生一個額外的代碼 -注釋；這可以幫助未來的審閱人員避免第一次出現的問題。 +註釋；這可以幫助未來的審閱人員避免第一次出現的問題。 一個致命的錯誤是忽視評論，希望它們會消失。它們不會走的。如果您在沒有對之前 收到的評論做出響應的情況下重新發布代碼，那麼很可能會發現補丁毫無用處。 -說到重新發布代碼：請記住，審閱者不會記住您上次發布的代碼的所有細節。因此， +說到重新發布代碼：請記住，審閱者不會記住您上次發佈的代碼的所有細節。因此， 提醒審閱人員以前提出的問題以及您如何處理這些問題總是一個好主意；補丁變更 日誌是提供此類信息的好地方。審閱者不必搜索列表檔案來熟悉上次所說的內容； 如果您幫助他們直接開始，當他們重新查看您的代碼時，心情會更好。 -如果你已經試著做正確的事情，但事情仍然沒有進展呢？大多數技術上的分歧都可以 +如果你已經試着做正確的事情，但事情仍然沒有進展呢？大多數技術上的分歧都可以 通過討論來解決，但有時人們仍需要做出決定。如果你真的認爲這個決定對你不利， -你可以試著向有更高權力的人上訴。對於本文，更高權力的人是 Andrew Morton 。 +你可以試着向有更高權力的人上訴。對於本文，更高權力的人是 Andrew Morton 。 Andrew 在內核開發社區中非常受尊敬；他經常爲似乎被絕望阻塞的事情清障。儘管 如此，不應輕易就直接找 Andrew ，也不應在所有其他替代方案都被嘗試之前找他。 當然，記住，他也可能不同意你的意見。 @@ -95,7 +95,7 @@ Andrew 在內核開發社區中非常受尊敬；他經常爲似乎被絕望阻 包含在子系統樹中可以提高補丁的可見性。現在，使用該樹的其他開發人員將默認獲 得補丁。子系統樹通常也爲Linux提供支持，使其內容對整個開發社區可見。在這一點 -上，您很可能會從一組新的審閱者那裡得到更多的評論；這些評論需要像上一輪那樣 +上，您很可能會從一組新的審閱者那裏得到更多的評論；這些評論需要像上一輪那樣 得到回應。 在這時也會發生點什麼，這取決於你的補丁的性質，是否與其他人正在做的工作發生 @@ -114,23 +114,23 @@ Andrew 在內核開發社區中非常受尊敬；他經常爲似乎被絕望阻 這種誘惑，您仍然需要對有問題或建議的開發人員作出響應。 不過，更重要的是：將代碼包含在主線中會將代碼交給更多的一些測試人員。即使您 -爲尚未可用的硬體提供了驅動程序，您也會驚訝於有多少人會將您的代碼構建到內核 +爲尚未可用的硬件提供了驅動程序，您也會驚訝於有多少人會將您的代碼構建到內核 中。當然，如果有測試人員，也可能會有錯誤報告。 -最糟糕的錯誤報告是回歸。如果你的補丁導致回歸，你會發現多到讓你不舒服的眼睛盯 -著你；回歸需要儘快修復。如果您不願意或無法修復回歸（其他人都不會爲您修復）， +最糟糕的錯誤報告是迴歸。如果你的補丁導致迴歸，你會發現多到讓你不舒服的眼睛盯 +着你；迴歸需要儘快修復。如果您不願意或無法修復迴歸（其他人都不會爲您修復）， 那麼在穩定期內，您的補丁幾乎肯定會被移除。除了否定您爲使補丁進入主線所做的 -所有工作之外，如果由於未能修復回歸而取消補丁，很可能會使將來的工作更難被合併。 +所有工作之外，如果由於未能修復迴歸而取消補丁，很可能會使將來的工作更難被合併。 -在處理完任何回歸之後，可能還有其他普通缺陷需要處理。穩定期是修復這些錯誤並 -確保代碼在主線內核版本中的首次發布儘可能可靠的最好機會。所以，請回應錯誤 +在處理完任何迴歸之後，可能還有其他普通缺陷需要處理。穩定期是修復這些錯誤並 +確保代碼在主線內核版本中的首次發佈儘可能可靠的最好機會。所以，請回應錯誤 報告，並儘可能解決問題。這就是穩定期的目的；一旦解決了舊補丁的任何問題，就 可以開始盡情創建新補丁。 別忘了，還有其他節點也可能會創建缺陷報告：下一個主線穩定版本，當著名的發行 商選擇包含您補丁的內核版本時等等。繼續響應這些報告是您工作的基本素養。但是 如果這不能提供足夠的動機，那麼也需要考慮：開發社區會記住那些在合併後對代碼 -失去興趣的開發人員。下一次你發布補丁時，他們會以你以後不會持續維護它爲前提 +失去興趣的開發人員。下一次你發佈補丁時，他們會以你以後不會持續維護它爲前提 來評估它。 其他可能發生的事情 @@ -141,15 +141,15 @@ Andrew 在內核開發社區中非常受尊敬；他經常爲似乎被絕望阻 維護人員（確保包含一個正確的From:行，這樣屬性是正確的，並添加一個您自己的 signoff ），或者回復一個 Acked-by: 讓原始發送者向上發送它。 -如果您不同意補丁，請禮貌地回復，解釋原因。如果可能的話，告訴作者需要做哪些 -更改才能讓您接受補丁。合併代碼的編寫者和維護者所反對的補丁的確存在著一定的 +如果您不同意補丁，請禮貌地回覆，解釋原因。如果可能的話，告訴作者需要做哪些 +更改才能讓您接受補丁。合併代碼的編寫者和維護者所反對的補丁的確存在着一定的 阻力，但僅此而已。如果你被認爲不必要的阻礙了好的工作，那麼這些補丁最終會 繞過你並進入主線。在Linux內核中，沒有人對任何代碼擁有絕對的否決權。可能除 了Linus。 -在非常罕見的情況下，您可能會看到完全不同的東西：另一個開發人員發布了針對您 -的問題的不同解決方案。在這時，兩個補丁之一可能不會被合併，「我的補丁首先 -發布」不被認爲是一個令人信服的技術論據。如果有別人的補丁取代了你的補丁而進 +在非常罕見的情況下，您可能會看到完全不同的東西：另一個開發人員發佈了針對您 +的問題的不同解決方案。在這時，兩個補丁之一可能不會被合併，“我的補丁首先 +發佈”不被認爲是一個令人信服的技術論據。如果有別人的補丁取代了你的補丁而進 入了主線，那麼只有一種方法可以回應你：很高興你的問題解決了，請繼續工作吧。 以這種方式把某人的工作推到一邊可能導致傷心和氣餒，但是社區會記住你的反應， 即使很久以後他們已經忘記了誰的補丁真正被合併。 diff --git a/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst b/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst index 4fbc104a37ca..59aa088decbf 100644 --- a/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst +++ b/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst @@ -24,14 +24,14 @@ 使用Git管理補丁 --------------- -內核使用分布式版本控制始於2002年初，當時Linus首次開始使用專有的Bitkeeper應用 -程序。雖然BitKeeper存在爭議，但它所體現的軟體版本管理方法卻肯定不是。分布式 +內核使用分佈式版本控制始於2002年初，當時Linus首次開始使用專有的Bitkeeper應用 +程序。雖然BitKeeper存在爭議，但它所體現的軟件版本管理方法卻肯定不是。分佈式 版本控制可以立即加速內核開發項目。現在有好幾種免費的BitKeeper替代品。 但無論好壞，內核項目都已經選擇了Git作爲其工具。 -使用Git管理補丁可以使開發人員的生活更加輕鬆，尤其是隨著補丁數量的增長。Git也 +使用Git管理補丁可以使開發人員的生活更加輕鬆，尤其是隨着補丁數量的增長。Git也 有其粗糙的邊角和一定的危險性，它是一個年輕和強大的工具，仍然在其開發人員完善 -中。本文檔不會試圖教會讀者如何使用git；這會是個巨長的文檔。相反，這裡的重點 +中。本文檔不會試圖教會讀者如何使用git；這會是個巨長的文檔。相反，這裏的重點 將是Git如何特別適合內核開發過程。想要加快用Git速度的開發人員可以在以下網站上 找到更多信息： @@ -42,22 +42,22 @@ 同時網上也能找到各種各樣的教程。 在嘗試使用它生成補丁供他人使用之前，第一要務是閱讀上述網頁，對Git的工作方式 -有一個紮實的了解。使用Git的開發人員應能進行拉取主線存儲庫的副本，查詢修訂 -歷史，提交對樹的更改，使用分支等操作。了解Git用於重寫歷史的工具（如rebase） -也很有用。Git有自己的術語和概念；Git的新用戶應該了解引用、遠程分支、索引、 -快進合併、推拉、游離頭等。一開始可能有點嚇人，但這些概念不難通過一點學習來 +有一個紮實的瞭解。使用Git的開發人員應能進行拉取主線存儲庫的副本，查詢修訂 +歷史，提交對樹的更改，使用分支等操作。瞭解Git用於重寫歷史的工具（如rebase） +也很有用。Git有自己的術語和概念；Git的新用戶應該瞭解引用、遠程分支、索引、 +快進合併、推拉、遊離頭等。一開始可能有點嚇人，但這些概念不難通過一點學習來 理解。 使用git生成通過電子郵件提交的補丁是提高速度的一個很好的練習。 -當您準備好開始建立Git樹供其他人查看時，無疑需要一個可以從中拉取的伺服器。 -如果您有一個可以訪問網際網路的系統，那麼使用git-daemon設置這樣的伺服器相對 +當您準備好開始建立Git樹供其他人查看時，無疑需要一個可以從中拉取的服務器。 +如果您有一個可以訪問因特網的系統，那麼使用git-daemon設置這樣的服務器相對 簡單。同時，免費的公共託管網站（例如github）也開始出現在網絡上。成熟的開發 人員可以在kernel.org上獲得一個帳戶，但這些帳戶並不容易得到；更多有關信息， 請參閱 https://kernel.org/faq/ 。 -正常的Git工作流程涉及到許多分支的使用。每一條開發線都可以分爲單獨的「主題 -分支」，並獨立維護。Git的分支很容易使用，沒有理由不使用它們。而且，在任何 +正常的Git工作流程涉及到許多分支的使用。每一條開發線都可以分爲單獨的“主題 +分支”，並獨立維護。Git的分支很容易使用，沒有理由不使用它們。而且，在任何 情況下，您都不應該在任何您打算讓其他人從中拉取的分支中進行開發。應該小心地 創建公開可用的分支；當開發分支處於完整狀態並已準備好時(而不是之前）才合併 開發分支的補丁。 @@ -72,10 +72,10 @@ Git提供了一些強大的工具，可以讓您重寫開發歷史。一個不 簡單癡迷。重寫歷史將重寫該歷史中包含的更改，將經過測試（希望如此）的內核樹 變爲未經測試的內核樹。除此之外，如果開發人員沒有共享項目歷史，他們就無法 輕鬆地協作；如果您重寫了其他開發人員拉入他們存儲庫的歷史，您將使這些開發 -人員的生活更加困難。因此，這裡有一個簡單的經驗法則：被導出到其他地方的歷史 +人員的生活更加困難。因此，這裏有一個簡單的經驗法則：被導出到其他地方的歷史 在此後通常被認爲是不可變的。 -因此，一旦將一組更改推送到公開可用的伺服器上，就不應該重寫這些更改。如果您 +因此，一旦將一組更改推送到公開可用的服務器上，就不應該重寫這些更改。如果您 嘗試強制進行無法快進合併的更改（即不共享同一歷史記錄的更改），Git將嘗試強制 執行此規則。這可能覆蓋檢查，有時甚至需要重寫導出的樹。在樹之間移動變更集以 避免linux-next中的衝突就是一個例子。但這種行爲應該是罕見的。這就是爲什麼 @@ -86,9 +86,9 @@ Git提供了一些強大的工具，可以讓您重寫開發歷史。一個不 對於一個私有的分支，rebasing 可能是一個很容易跟上另一棵樹的方法，但是一旦 一棵樹被導出到外界，rebasing就不可取了。一旦發生這種情況，就必須進行完全 合併（merge）。合併有時是很有意義的，但是過於頻繁的合併會不必要地擾亂歷史。 -在這種情況下建議的做法是不要頻繁合併，通常只在特定的發布點（如主線-rc發布） +在這種情況下建議的做法是不要頻繁合併，通常只在特定的發佈點（如主線-rc發佈） 合併。如果您對特定的更改感到緊張，則可以始終在私有分支中執行測試合併。在 -這種情況下，git「rerere」工具很有用；它能記住合併衝突是如何解決的，這樣您 +這種情況下，git“rerere”工具很有用；它能記住合併衝突是如何解決的，這樣您 就不必重複相同的工作。 關於Git這樣的工具的一個最大的反覆抱怨是：補丁從一個存儲庫到另一個存儲庫的 @@ -98,36 +98,36 @@ Git提供了一些強大的工具，可以讓您重寫開發歷史。一個不 :: - 你可以給我發補丁，但當我從你那裡拉取一個Git補丁時，我需要知道你清楚 + 你可以給我發補丁，但當我從你那裏拉取一個Git補丁時，我需要知道你清楚 自己在做什麼，我需要能夠相信事情而 *無需* 手動檢查每個單獨的更改。 （http://lwn.net/Articles/224135/）。 -爲了避免這種情況，請確保給定分支中的所有補丁都與相關主題緊密相關；「驅動程序 -修復」分支不應更改核心內存管理代碼。而且，最重要的是，不要使用Git樹來繞過 -審查過程。不時的將樹的摘要發布到相關的列表中，在合適時候請求linux-next中 +爲了避免這種情況，請確保給定分支中的所有補丁都與相關主題緊密相關；“驅動程序 +修復”分支不應更改核心內存管理代碼。而且，最重要的是，不要使用Git樹來繞過 +審查過程。不時的將樹的摘要發佈到相關的列表中，在合適時候請求linux-next中 包含該樹。 如果其他人開始發送補丁以包含到您的樹中，不要忘記審閱它們。還要確保您維護正確 -的作者信息； git 「am」工具在這方面做得最好，但是如果補丁通過第三方轉發給您， -您可能需要在補丁中添加「From:」行。 +的作者信息； git “am”工具在這方面做得最好，但是如果補丁通過第三方轉發給您， +您可能需要在補丁中添加“From:”行。 請求拉取時，請務必提供所有相關信息：樹的位置、要拉取的分支以及拉取將導致的 更改。在這方面 git request-pull 命令非常有用；它將按照其他開發人員所期望的 -格式化請求，並檢查以確保您已記得將這些更改推送到公共伺服器。 +格式化請求，並檢查以確保您已記得將這些更改推送到公共服務器。 審閱補丁 -------- -一些讀者顯然會反對將本節與「高級主題」放在一起，因爲即使是剛開始的內核開發人員 -也應該審閱補丁。當然，沒有比查看其他人發布的代碼更好的方法來學習如何在內核環境 +一些讀者顯然會反對將本節與“高級主題”放在一起，因爲即使是剛開始的內核開發人員 +也應該審閱補丁。當然，沒有比查看其他人發佈的代碼更好的方法來學習如何在內核環境 中編程了。此外，審閱者永遠供不應求；通過審閱代碼，您可以對整個流程做出重大貢獻。 審查代碼可能是一副令人生畏的圖景，特別是對一個新的內核開發人員來說，他們 -可能會對公開詢問代碼感到緊張，而這些代碼是由那些有更多經驗的人發布的。不過， +可能會對公開詢問代碼感到緊張，而這些代碼是由那些有更多經驗的人發佈的。不過， 即使是最有經驗的開發人員編寫的代碼也可以得到改進。也許對（所有）審閱者最好 -的建議是：把審閱評論當成問題而不是批評。詢問「在這條路徑中如何釋放鎖？」 -總是比說「這裡的鎖是錯誤的」更好。 +的建議是：把審閱評論當成問題而不是批評。詢問“在這條路徑中如何釋放鎖？” +總是比說“這裏的鎖是錯誤的”更好。 不同的開發人員將從不同的角度審查代碼。部分人會主要關注代碼風格以及代碼行是 否有尾隨空格。其他人會主要關注補丁作爲一個整體實現的變更是否對內核有好處。 diff --git a/Documentation/translations/zh_TW/process/8.Conclusion.rst b/Documentation/translations/zh_TW/process/8.Conclusion.rst index 044fcc118bef..3ae08a41fd78 100644 --- a/Documentation/translations/zh_TW/process/8.Conclusion.rst +++ b/Documentation/translations/zh_TW/process/8.Conclusion.rst @@ -17,13 +17,13 @@ 更多信息 ======== -關於Linux內核開發和相關主題的信息來源很多。首先是在內核原始碼分發中找到的 +關於Linux內核開發和相關主題的信息來源很多。首先是在內核源代碼分發中找到的 文檔目錄。頂級 -:ref:`Documentation/translations/zh_TW/process/howto.rst ` +:ref:`Documentation/translations/zh_CN/process/howto.rst ` 文件是一個重要的起點； -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst ` +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst ` 也是所有內核開發人員都應該閱讀的內容。許多內部內核API都是使用kerneldoc機制 -記錄的；「make htmldocs」或「make pdfdocs」可用於以HTML或PDF格式生成這些文檔 +記錄的；“make htmldocs”或“make pdfdocs”可用於以HTML或PDF格式生成這些文檔 （儘管某些發行版提供的tex版本會遇到內部限制，無法正確處理文檔）。 不同的網站在各個細節層次上討論內核開發。本文作者想謙虛地建議用 https://lwn.net/ @@ -35,7 +35,7 @@ https://kernelnewbies.org/ -當然，也不應該忘記 https://kernel.org/ ，這是內核發布信息的最終位置。 +當然，也不應該忘記 https://kernel.org/ ，這是內核發佈信息的最終位置。 關於內核開發有很多書： @@ -47,7 +47,7 @@ 《深入理解Linux內核》(Daniel Bovet和Marco Cesati） 然而，所有這些書都有一個共同的缺點：它們上架時就往往有些過時，而且已經上架 -一段時間了。不過，在那裡還是可以找到相當多的好信息。 +一段時間了。不過，在那裏還是可以找到相當多的好信息。 有關git的文檔，請訪問： @@ -61,7 +61,7 @@ 祝賀所有通過這篇冗長的文檔的人。希望它能夠幫助您理解Linux內核是如何開發的， 以及您如何參與這個過程。 -最後，重要的是參與。任何開源軟體項目都不會超過其貢獻者投入其中的總和。Linux +最後，重要的是參與。任何開源軟件項目都不會超過其貢獻者投入其中的總和。Linux 內核的發展速度和以前一樣快，因爲它得到了大量開發人員的幫助，他們都在努力使它 變得更好。內核是一個最成功的例子，說明了當成千上萬的人爲了一個共同的目標一起 工作時，可以做出什麼。 diff --git a/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst b/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst index 949d831aaf6c..70293eb332b9 100644 --- a/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst +++ b/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst @@ -8,34 +8,34 @@ .. _tw_code_of_conduct_interpretation: -Linux內核貢獻者契約行為準則解釋 +Linux內核貢獻者契約行爲準則解釋 =============================== -:ref:`tw_code_of_conduct` 準則是一個通用文檔，旨在爲幾乎所有開源社區提供一套規則。 +:ref:`cn_code_of_conduct` 準則是一個通用文檔，旨在爲幾乎所有開源社區提供一套規則。 每個開源社區都是獨一無二的，Linux內核也不例外。因此，本文描述了Linux內核社區中 -如何解釋它。我們也不希望這種解釋隨著時間的推移是靜態的，並將根據需要進行調整。 +如何解釋它。我們也不希望這種解釋隨着時間的推移是靜態的，並將根據需要進行調整。 -與開發軟體的「傳統」方法相比，Linux內核開發工作是一個非常個人化的過程。你的貢獻 +與開發軟件的“傳統”方法相比，Linux內核開發工作是一個非常個人化的過程。你的貢獻 和背後的想法將被仔細審查，往往導致批判和批評。審查將幾乎總是需要改進，材料才 能包括在內核中。要知道這是因爲所有相關人員都希望看到Linux整體成功的最佳解決方 -案。這個開發過程已經被證明可以創建有史以來最健壯的作業系統內核，我們不想做任何 +案。這個開發過程已經被證明可以創建有史以來最健壯的操作系統內核，我們不想做任何 事情來導致提交質量和最終結果的下降。 維護者 ------ -行為準則多次使用「維護者」一詞。在內核社區中，「維護者」是負責子系統、驅動程序或 -文件的任何人，並在內核原始碼樹的維護者文件中列出。 +行爲準則多次使用“維護者”一詞。在內核社區中，“維護者”是負責子系統、驅動程序或 +文件的任何人，並在內核源代碼樹的維護者文件中列出。 責任 ---- -《行為準則》提到了維護人員的權利和責任，這需要進一步澄清。 +《行爲準則》提到了維護人員的權利和責任，這需要進一步澄清。 首先，最重要的是，有一個合理的期望是由維護人員通過實例來領導。 也就是說，我們的社區是廣闊的，對維護者沒有新的要求，他們單方面處理其他人在 -他們活躍的社區的行爲。這一責任由我們所有人承擔，最終《行為準則》記錄了最終的 +他們活躍的社區的行爲。這一責任由我們所有人承擔，最終《行爲準則》記錄了最終的 上訴路徑，以防有關行爲問題的問題懸而未決。 維護人員應該願意在出現問題時提供幫助，並在需要時與社區中的其他人合作。如果您 @@ -43,10 +43,10 @@ Linux內核貢獻者契約行為準則解釋 除非您願意，否則不會將其視爲違規報告。如果您不確定是否該聯繫TAB 或任何其他維 護人員，請聯繫我們的衝突調解人 Mishi Choudhary 。 -最後，「善待對方」才是每個人的最終目標。我們知道每個人都是人，有時我們都會失敗， -但我們所有人的首要目標應該是努力友好地解決問題。執行行為準則將是最後的選擇。 +最後，“善待對方”纔是每個人的最終目標。我們知道每個人都是人，有時我們都會失敗， +但我們所有人的首要目標應該是努力友好地解決問題。執行行爲準則將是最後的選擇。 -我們的目標是創建一個強大的、技術先進的作業系統，以及所涉及的技術複雜性，這自 +我們的目標是創建一個強大的、技術先進的操作系統，以及所涉及的技術複雜性，這自 然需要專業知識和決策。 所需的專業知識因貢獻領域而異。它主要由上下文和技術複雜性決定，其次由貢獻者和 @@ -55,58 +55,58 @@ Linux內核貢獻者契約行為準則解釋 專家的期望和決策都要經過討論，但在最後，爲了取得進展，必須能夠做出決策。這一 特權掌握在維護人員和項目領導的手中，預計將善意使用。 -因此，設定專業知識期望、作出決定和拒絕不適當的貢獻不被視爲違反行為準則。 +因此，設定專業知識期望、作出決定和拒絕不適當的貢獻不被視爲違反行爲準則。 雖然維護人員一般都歡迎新來者，但他們幫助（新）貢獻者克服障礙的能力有限，因此 -他們必須確定優先事項。這也不應被視爲違反了行為準則。內核社區意識到這一點，並 +他們必須確定優先事項。這也不應被視爲違反了行爲準則。內核社區意識到這一點，並 以各種形式提供入門級節目，如 kernelnewbies.org 。 範圍 ---- -Linux內核社區主要在一組公共電子郵件列表上進行交互，這些列表分布在由多個不同 -公司或個人控制的多個不同伺服器上。所有這些列表都在內核原始碼樹中的 +Linux內核社區主要在一組公共電子郵件列表上進行交互，這些列表分佈在由多個不同 +公司或個人控制的多個不同服務器上。所有這些列表都在內核源代碼樹中的 MAINTAINERS 文件中定義。發送到這些郵件列表的任何電子郵件都被視爲包含在行爲 準則中。 使用 kernel.org bugzilla和其他子系統bugzilla 或bug跟蹤工具的開發人員應該遵循 -行為準則的指導原則。Linux內核社區沒有「官方」項目電子郵件地址或「官方」社交媒體 -地址。使用kernel.org電子郵件帳戶執行的任何活動必須遵循爲kernel.org發布的行爲 +行爲準則的指導原則。Linux內核社區沒有“官方”項目電子郵件地址或“官方”社交媒體 +地址。使用kernel.org電子郵件帳戶執行的任何活動必須遵循爲kernel.org發佈的行爲 準則，就像任何使用公司電子郵件帳戶的個人必須遵循該公司的特定規則一樣。 -行為準則並不禁止在郵件列表消息、內核更改日誌消息或代碼注釋中繼續包含名稱、 +行爲準則並不禁止在郵件列表消息、內核更改日誌消息或代碼註釋中繼續包含名稱、 電子郵件地址和相關注釋。 -其他論壇中的互動包括在適用於上述論壇的任何規則中，通常不包括在行為準則中。 +其他論壇中的互動包括在適用於上述論壇的任何規則中，通常不包括在行爲準則中。 除了在極端情況下可考慮的例外情況。 -提交給內核的貢獻應該使用適當的語言。在行為準則之前已經存在的內容現在不會被 +提交給內核的貢獻應該使用適當的語言。在行爲準則之前已經存在的內容現在不會被 視爲違反。然而，不適當的語言可以被視爲一個bug；如果任何相關方提交補丁， 這樣的bug將被更快地修復。當前屬於用戶/內核API的一部分的表達式，或者反映已 -發布標準或規範中使用的術語的表達式，不被視爲bug。 +發佈標準或規範中使用的術語的表達式，不被視爲bug。 執行 ---- -行為準則中列出的地址屬於行為準則委員會。https://kernel.org/code-of-conduct.html +行爲準則中列出的地址屬於行爲準則委員會。https://kernel.org/code-of-conduct.html 列出了在任何給定時間接收這些電子郵件的確切成員。成員不能訪問在加入委員會之前 或離開委員會之後所做的報告。 -最初的行為準則委員會由TAB的志願者以及作爲中立第三方的專業調解人組成。委員會 +最初的行爲準則委員會由TAB的志願者以及作爲中立第三方的專業調解人組成。委員會 的首要任務是建立文件化的流程，並將其公開。 如果報告人不希望將整個委員會納入投訴或關切，可直接聯繫委員會的任何成員，包括 調解人。 -行為準則委員會根據流程審查案例（見上文），並根據需要和適當與TAB協商，例如請求 +行爲準則委員會根據流程審查案例（見上文），並根據需要和適當與TAB協商，例如請求 和接收有關內核社區的信息。 委員會做出的任何決定都將提交到表中，以便在必要時與相關維護人員一起執行。行爲 準則委員會的決定可以通過三分之二的投票推翻。 -每季度，行為準則委員會和標籤將提供一份報告，概述行為準則委員會收到的匿名報告 +每季度，行爲準則委員會和標籤將提供一份報告，概述行爲準則委員會收到的匿名報告 及其狀態，以及任何否決決定的細節，包括完整和可識別的投票細節。 -我們希望在啓動期之後爲行為準則委員會人員配備建立一個不同的流程。發生此情況時， +我們希望在啓動期之後爲行爲準則委員會人員配備建立一個不同的流程。發生此情況時， 將使用該信息更新此文檔。 diff --git a/Documentation/translations/zh_TW/process/code-of-conduct.rst b/Documentation/translations/zh_TW/process/code-of-conduct.rst index 716e5843b6e9..588bc364f6ed 100644 --- a/Documentation/translations/zh_TW/process/code-of-conduct.rst +++ b/Documentation/translations/zh_TW/process/code-of-conduct.rst @@ -8,7 +8,7 @@ .. _tw_code_of_conduct: -貢獻者契約行為準則 +貢獻者契約行爲準則 ++++++++++++++++++ 我們的誓言 @@ -35,7 +35,7 @@ * 使用性意味的語言或意象以及不受歡迎的性注意或者更過分的行爲 * 煽動、侮辱/貶損評論以及個人或政治攻擊 * 公開或私下騷擾 -* 未經明確許可，發布他人的私人信息，如物理或電子地址。 +* 未經明確許可，發佈他人的私人信息，如物理或電子地址。 * 在專業場合被合理認爲不適當的其他行爲 我們的責任 @@ -44,33 +44,33 @@ 維護人員負責澄清可接受行爲的標準，並應針對任何不可接受行爲採取適當和公平的 糾正措施。 -維護人員有權和責任刪除、編輯或拒絕與本行為準則不一致的評論、承諾、代碼、 +維護人員有權和責任刪除、編輯或拒絕與本行爲準則不一致的評論、承諾、代碼、 wiki編輯、問題和其他貢獻，或暫時或永久禁止任何貢獻者從事他們認爲不適當、 威脅、冒犯或有害的其他行爲。 範圍 ==== -當個人代表項目或其社區時，本行為準則既適用於項目空間，也適用於公共空間。 +當個人代表項目或其社區時，本行爲準則既適用於項目空間，也適用於公共空間。 代表一個項目或社區的例子包括使用一個正式的項目電子郵件地址，通過一個正式 -的社交媒體帳戶發布，或者在在線或離線事件中擔任指定的代表。項目維護人員可以 +的社交媒體帳戶發佈，或者在在線或離線事件中擔任指定的代表。項目維護人員可以 進一步定義和澄清項目的表示。 執行 ==== -如有濫用、騷擾或其他不可接受的行爲，可聯繫行為準則委員會。 -所有投訴都將接受審查和調查，並將得到必要和適當的答覆。行為準則委員會有義務 -對事件報告人保密。具體執行政策的進一步細節可單獨公布。 +如有濫用、騷擾或其他不可接受的行爲，可聯繫行爲準則委員會。 +所有投訴都將接受審查和調查，並將得到必要和適當的答覆。行爲準則委員會有義務 +對事件報告人保密。具體執行政策的進一步細節可單獨公佈。 歸屬 ==== -本行為準則改編自《貢獻者契約》，版本1.4，可從 +本行爲準則改編自《貢獻者契約》，版本1.4，可從 https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 獲取。 解釋 ==== -有關Linux內核社區如何解釋此文檔，請參閱 :ref:`tw_code_of_conduct_interpretation` +有關Linux內核社區如何解釋此文檔，請參閱 :ref:`cn_code_of_conduct_interpretation` diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst index 61e614aad6a7..d49b9db21011 100644 --- a/Documentation/translations/zh_TW/process/coding-style.rst +++ b/Documentation/translations/zh_TW/process/coding-style.rst @@ -6,38 +6,35 @@ .. _tw_codingstyle: -譯者:: - - 中文版維護者： 張樂 Zhang Le - 中文版翻譯者： 張樂 Zhang Le - 中文版校譯者： 王聰 Wang Cong - wheelz - 管旭東 Xudong Guan - Li Zefan - Wang Chen - Hu Haowen +:校譯: + - 王聰 Wang Cong + - wheelz + - 管旭東 Xudong Guan + - Li Zefan + - Wang Chen + - Hu Haowen Linux 內核代碼風格 -========================= +================== 這是一個簡短的文檔，描述了 linux 內核的首選代碼風格。代碼風格是因人而異的， 而且我不願意把自己的觀點強加給任何人，但這就像我去做任何事情都必須遵循的原則 -那樣，我也希望在絕大多數事上保持這種的態度。請 (在寫代碼時) 至少考慮一下這裡 +那樣，我也希望在絕大多數事上保持這種的態度。請 (在寫代碼時) 至少考慮一下這裏 的代碼風格。 -首先，我建議你列印一份 GNU 代碼規範，然後不要讀。燒了它，這是一個具有重大象徵 +首先，我建議你打印一份 GNU 代碼規範，然後不要讀。燒了它，這是一個具有重大象徵 性意義的動作。 不管怎樣，現在我們開始： 1) 縮進 --------------- +------- -制表符是 8 個字符，所以縮進也是 8 個字符。有些異端運動試圖將縮進變爲 4 (甚至 +製表符是 8 個字符，所以縮進也是 8 個字符。有些異端運動試圖將縮進變爲 4 (甚至 2！) 字符深，這幾乎相當於嘗試將圓周率的值定義爲 3。 -理由：縮進的全部意義就在於清楚的定義一個控制塊起止於何處。尤其是當你盯著你的 +理由：縮進的全部意義就在於清楚的定義一個控制塊起止於何處。尤其是當你盯着你的 屏幕連續看了 20 小時之後，你將會發現大一點的縮進會使你更容易分辨縮進。 現在，有些人會抱怨 8 個字符的縮進會使代碼向右邊移動的太遠，在 80 個字符的終端 @@ -69,39 +66,60 @@ Linux 內核代碼風格 break; } -不要把多個語句放在一行里，除非你有什麼東西要隱藏： +不要把多個語句放在一行裏，除非你有什麼東西要隱藏： .. code-block:: c if (condition) do_this; do_something_everytime; -也不要在一行里放多個賦值語句。內核代碼風格超級簡單。就是避免可能導致別人誤讀 +不要使用逗號來避免使用大括號： + +.. code-block:: c + + if (condition) + do_this(), do_that(); + +使用大括號包裹多語句： + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } + +也不要在一行裏放多個賦值語句。內核代碼風格超級簡單。就是避免可能導致別人誤讀 的表達式。 -除了注釋、文檔和 Kconfig 之外，不要使用空格來縮進，前面的例子是例外，是有意爲 +除了註釋、文檔和 Kconfig 之外，不要使用空格來縮進，前面的例子是例外，是有意爲 之。 選用一個好的編輯器，不要在行尾留空格。 2) 把長的行和字符串打散 ------------------------------- +----------------------- 代碼風格的意義就在於使用平常使用的工具來維持代碼的可讀性和可維護性。 每一行的長度的限制是 80 列，我們強烈建議您遵守這個慣例。 長於 80 列的語句要打散成有意義的片段。除非超過 80 列能顯著增加可讀性，並且不 -會隱藏信息。子片段要明顯短於母片段，並明顯靠右。這同樣適用於有著很長參數列表 -的函數頭。然而，絕對不要打散對用戶可見的字符串，例如 printk 信息，因爲這樣就 +會隱藏信息。 + +子片段要明顯短於母片段，並明顯靠右。一種非常常用的樣式是將子體與函數左括號對齊。 + +這同樣適用於有着很長參數列表的函數頭。 + +然而，絕對不要打散對用戶可見的字符串，例如 printk 信息，因爲這樣就 很難對它們 grep。 3) 大括號和空格的放置 ------------------------------- +--------------------- -C 語言風格中另外一個常見問題是大括號的放置。和縮進大小不同，選擇或棄用某种放 +C 語言風格中另外一個常見問題是大括號的放置。和縮進大小不同，選擇或棄用某種放 置策略並沒有多少技術上的原因，不過首選的方式，就像 Kernighan 和 Ritchie 展示 給我們的，是把起始大括號放在行尾，而把結束大括號放在行首，所以： @@ -135,12 +153,12 @@ C 語言風格中另外一個常見問題是大括號的放置。和縮進大小 body of function } -全世界的異端可能會抱怨這個不一致性是... 呃... 不一致的，不過所有思維健全的人 +全世界的異端可能會抱怨這個不一致性是……呃……不一致，不過所有思維健全的人 都知道 (a) K&R 是 **正確的** 並且 (b) K&R 是正確的。此外，不管怎樣函數都是特 殊的 (C 函數是不能嵌套的)。 -注意結束大括號獨自占據一行，除非它後面跟著同一個語句的剩餘部分，也就是 do 語 -句中的 "while" 或者 if 語句中的 "else"，像這樣： +注意結束大括號獨自佔據一行，除非它後面跟着同一個語句的剩餘部分，也就是 do 語 +句中的 ``while`` 或者 if 語句中的 ``else`` ，像這樣： .. code-block:: c @@ -164,7 +182,7 @@ C 語言風格中另外一個常見問題是大括號的放置。和縮進大小 也請注意這種大括號的放置方式也能使空 (或者差不多空的) 行的數量最小化，同時不 失可讀性。因此，由於你的屏幕上的新行是不可再生資源 (想想 25 行的終端屏幕)，你 -將會有更多的空行來放置注釋。 +將會有更多的空行來放置註釋。 當只有一個單獨的語句的時候，不用加不必要的大括號。 @@ -194,12 +212,12 @@ C 語言風格中另外一個常見問題是大括號的放置。和縮進大小 } 3.1) 空格 -******************** +********* Linux 內核的空格使用方式 (主要) 取決於它是用於函數還是關鍵字。(大多數) 關鍵字 後要加一個空格。值得注意的例外是 sizeof, typeof, alignof 和 __attribute__，這 -些關鍵字某些程度上看起來更像函數 (它們在 Linux 里也常常伴隨小括號而使用，儘管 -在 C 里這樣的小括號不是必需的，就像 ``struct fileinfo info;`` 聲明過後的 +些關鍵字某些程度上看起來更像函數 (它們在 Linux 裏也常常伴隨小括號而使用，儘管 +在 C 裏這樣的小括號不是必需的，就像 ``struct fileinfo info;`` 聲明過後的 ``sizeof info``)。 所以在這些關鍵字之後放一個空格:: @@ -213,7 +231,7 @@ Linux 內核的空格使用方式 (主要) 取決於它是用於函數還是關 s = sizeof(struct file); -不要在小括號里的表達式兩側加空格。這是一個 **反例** ： +不要在小括號裏的表達式兩側加空格。這是一個 **反例** ： .. code-block:: c @@ -257,10 +275,10 @@ Linux 內核的空格使用方式 (主要) 取決於它是用於函數還是關 4) 命名 ------------------------------- +------- -C 是一個簡樸的語言，你的命名也應該這樣。和 Modula-2 和 Pascal 程式設計師不同， -C 程式設計師不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的名字。C 程式設計師會 +C 是一個簡樸的語言，你的命名也應該這樣。和 Modula-2 和 Pascal 程序員不同， +C 程序員不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的名字。C 程序員會 稱那個變量爲 ``tmp`` ，這樣寫起來會更容易，而且至少不會令其難於理解。 不過，雖然混用大小寫的名字是不提倡使用的，但是全局變量還是需要一個具描述性的 @@ -271,23 +289,42 @@ C 程式設計師不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的 ``count_active_users()`` 或者類似的名字，你不應該叫它 ``cntuser()`` 。 在函數名中包含函數類型 (所謂的匈牙利命名法) 是腦子出了問題——編譯器知道那些類 -型而且能夠檢查那些類型，這樣做只能把程式設計師弄糊塗了。難怪微軟總是製造出有問題 -的程序。 +型而且能夠檢查那些類型，這樣做只能把程序員弄糊塗了。 本地變量名應該簡短，而且能夠表達相關的含義。如果你有一些隨機的整數型的循環計 數器，它應該被稱爲 ``i`` 。叫它 ``loop_counter`` 並無益處，如果它沒有被誤解的 可能的話。類似的， ``tmp`` 可以用來稱呼任意類型的臨時變量。 如果你怕混淆了你的本地變量名，你就遇到另一個問題了，叫做函數增長荷爾蒙失衡綜 -合症。請看第六章 (函數)。 +合徵。請看第六章 (函數)。 + +對於符號名稱和文檔，避免引入新的“master/slave”（或獨立於“master”的“slave”） +和“blacklist/whitelist”。 + +“master/slave”推薦替換爲： + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader/follower' + 'director/performer' + +“blacklist/whitelist”推薦替換爲： + 'denylist/allowlist' + 'blocklist/passlist' + +引入新用法的例外情況是：維護用戶空間ABI/API，或更新現有（截至2020年）硬件或 +協議規範的代碼時要求這些術語。對於新規範，儘可能將術語的規範用法轉換爲內核 +編碼標準。 +.. warning:: + 以上主從、黑白名單規則不適用於中文文檔，請勿更改中文術語！ 5) Typedef ------------ +---------- 不要使用類似 ``vps_t`` 之類的東西。 -對結構體和指針使用 typedef 是一個 **錯誤** 。當你在代碼里看到： +對結構體和指針使用 typedef 是一個 **錯誤** 。當你在代碼裏看到： .. code-block:: c @@ -312,13 +349,13 @@ C 程式設計師不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的 .. note:: - 不透明性和 "訪問函數" 本身是不好的。我們使用 pte_t 等類型的原因在於真 + 不透明性和“訪問函數”本身是不好的。我們使用 pte_t 等類型的原因在於真 的是完全沒有任何共用的可訪問信息。 (b) 清楚的整數類型，如此，這層抽象就可以 **幫助** 消除到底是 ``int`` 還是 ``long`` 的混淆。 - u8/u16/u32 是完全沒有問題的 typedef，不過它們更符合類別 (d) 而不是這裡。 + u8/u16/u32 是完全沒有問題的 typedef，不過它們更符合類別 (d) 而不是這裏。 .. note:: @@ -345,30 +382,30 @@ C 程式設計師不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的 (e) 可以在用戶空間安全使用的類型。 - 在某些用戶空間可見的結構體裡，我們不能要求 C99 類型而且不能用上面提到的 + 在某些用戶空間可見的結構體裏，我們不能要求 C99 類型而且不能用上面提到的 ``u32`` 類型。因此，我們在與用戶空間共享的所有結構體中使用 __u32 和類似 的類型。 可能還有其他的情況，不過基本的規則是 **永遠不要** 使用 typedef，除非你可以明 確的應用上述某個規則中的一個。 -總的來說，如果一個指針或者一個結構體裡的元素可以合理的被直接訪問到，那麼它們 +總的來說，如果一個指針或者一個結構體裏的元素可以合理的被直接訪問到，那麼它們 就不應該是一個 typedef。 6) 函數 ------------------------------- +------- 函數應該簡短而漂亮，並且只完成一件事情。函數應該可以一屏或者兩屏顯示完 (我們 都知道 ISO/ANSI 屏幕大小是 80x24)，只做一件事情，而且把它做好。 一個函數的最大長度是和該函數的複雜度和縮進級數成反比的。所以，如果你有一個理 論上很簡單的只有一個很長 (但是簡單) 的 case 語句的函數，而且你需要在每個 case -里做很多很小的事情，這樣的函數儘管很長，但也是可以的。 +裏做很多很小的事情，這樣的函數儘管很長，但也是可以的。 不過，如果你有一個複雜的函數，而且你懷疑一個天分不是很高的高中一年級學生可能 甚至搞不清楚這個函數的目的，你應該嚴格遵守前面提到的長度限制。使用輔助函數， -並爲之取個具描述性的名字 (如果你覺得它們的性能很重要的話，可以讓編譯器內聯它 +併爲之取個具描述性的名字 (如果你覺得它們的性能很重要的話，可以讓編譯器內聯它 們，這樣的效果往往會比你寫一個複雜函數的效果要好。) 函數的另外一個衡量標準是本地變量的數量。此數量不應超過 5－10 個，否則你的函數 @@ -376,7 +413,7 @@ C 程式設計師不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的 的同時跟蹤 7 個不同的事物，如果再增多的話，就會糊塗了。即便你聰穎過人，你也可 能會記不清你 2 個星期前做過的事情。 -在源文件里，使用空行隔開不同的函數。如果該函數需要被導出，它的 **EXPORT** 宏 +在源文件裏，使用空行隔開不同的函數。如果該函數需要被導出，它的 **EXPORT** 宏 應該緊貼在它的結束大括號之下。比如： .. code-block:: c @@ -387,12 +424,46 @@ C 程式設計師不使用類似 ThisVariableIsATemporaryCounter 這樣華麗的 } EXPORT_SYMBOL(system_is_up); -在函數原型中，包含函數名和它們的數據類型。雖然 C 語言裡沒有這樣的要求，在 -Linux 里這是提倡的做法，因爲這樣可以很簡單的給讀者提供更多的有價值的信息。 +6.1) 函數原型 +************* +在函數原型中包含參數名和它們的數據類型。雖然 C 語言裏沒有這樣的要求，但在 +Linux 裏這是提倡的做法，因爲這樣可以很簡單的給讀者提供更多的有價值的信息。 + +不要在函數聲明裏使用 ``extern`` 關鍵字，因爲這會導致代碼行變長，並且不是嚴格 +必需的。 + +寫函數原型時，請保持 `元素順序規則 `_ 。 +例如下列函數聲明:: + + __init void * __must_check action(enum magic value, size_t size, u8 count, + char *fmt, ...) __printf(4, 5) __malloc; + +推薦的函數原型元素順序是： + +- 儲存類型（下方的 ``static __always_inline`` ，注意 ``__always_inline`` + 技術上來講是個屬性但被當做 ``inline`` ） +- 儲存類型屬性（上方的 ``__init`` ——即節聲明，但也像 ``__cold`` ） +- 返回類型（上方的 ``void *`` ） +- 返回類型屬性（上方的 ``__must_check`` ） +- 函數名（上方的 ``action`` ） +- 函數參數（上方的 ``(enum magic value, size_t size, u8 count, char *fmt, ...)`` ， + 注意必須寫上參數名） +- 函數參數屬性（上方的 ``__printf(4, 5)`` ） +- 函數行爲屬性（上方的 ``__malloc`` ） + +請注意，對於函數 **定義** （即實際函數體），編譯器不允許在函數參數之後添加函 +數參數屬性。在這種情況下，它們應該跟隨存儲類型屬性（例如，與上面的 **聲明** +示例相比，請注意下面的 ``__printf(4, 5)`` 的位置發生了變化）:: + + static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, + size_t size, u8 count, char *fmt, ...) __malloc + { + ... + } 7) 集中的函數退出途徑 ------------------------------- +--------------------- 雖然被某些人聲稱已經過時，但是 goto 語句的等價物還是經常被編譯器所使用，具體 形式是無條件跳轉指令。 @@ -436,7 +507,7 @@ Linux 里這是提倡的做法，因爲這樣可以很簡單的給讀者提供 return result; } -一個需要注意的常見錯誤是 ``一個 err 錯誤`` ，就像這樣： +一個需要注意的常見錯誤是 ``單 err 錯誤`` ，就像這樣： .. code-block:: c @@ -459,22 +530,22 @@ Linux 里這是提倡的做法，因爲這樣可以很簡單的給讀者提供 理想情況下，你應該模擬錯誤來測試所有退出路徑。 -8) 注釋 ------------------------------- +8) 註釋 +------- -注釋是好的，不過有過度注釋的危險。永遠不要在注釋里解釋你的代碼是如何運作的： +註釋是好的，不過有過度註釋的危險。永遠不要在註釋裏解釋你的代碼是如何運作的： 更好的做法是讓別人一看你的代碼就可以明白，解釋寫的很差的代碼是浪費時間。 -一般的，你想要你的注釋告訴別人你的代碼做了什麼，而不是怎麼做的。也請你不要把 -注釋放在一個函數體內部：如果函數複雜到你需要獨立的注釋其中的一部分，你很可能 +一般來說你用註釋告訴別人你的代碼做了什麼，而不是怎麼做的。也請你不要把 +註釋放在一個函數體內部：如果函數複雜到你需要獨立的註釋其中的一部分，你很可能 需要回到第六章看一看。你可以做一些小注釋來註明或警告某些很聰明 (或者槽糕) 的 -做法，但不要加太多。你應該做的，是把注釋放在函數的頭部，告訴人們它做了什麼， +做法，但不要加太多。你應該做的，是把註釋放在函數的頭部，告訴人們它做了什麼， 也可以加上它做這些事情的原因。 -當注釋內核 API 函數時，請使用 kernel-doc 格式。請看 -Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 +當註釋內核 API 函數時，請使用 kernel-doc 格式。詳見 +Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。 -長 (多行) 注釋的首選風格是： +長 (多行) 註釋的首選風格是： .. code-block:: c @@ -487,7 +558,7 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 * with beginning and ending almost-blank lines. */ -對於在 net/ 和 drivers/net/ 的文件，首選的長 (多行) 注釋風格有些不同。 +對於在 net/ 和 drivers/net/ 的文件，首選的長 (多行) 註釋風格有些不同。 .. code-block:: c @@ -498,23 +569,24 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 * but there is no initial almost-blank line. */ -注釋數據也是很重要的，不管是基本類型還是衍生類型。爲了方便實現這一點，每一行 +註釋數據也是很重要的，不管是基本類型還是衍生類型。爲了方便實現這一點，每一行 應只聲明一個數據 (不要使用逗號來一次聲明多個數據)。這樣你就有空間來爲每個數據 寫一段小注釋來解釋它們的用途了。 9) 你已經把事情弄糟了 ------------------------------- +--------------------- -這沒什麼，我們都是這樣。可能你的使用了很長時間 Unix 的朋友已經告訴你 -``GNU emacs`` 能自動幫你格式化 C 原始碼，而且你也注意到了，確實是這樣，不過它 +這沒什麼，我們都是這樣。可能你長期使用 Unix 的朋友已經告訴你 +``GNU emacs`` 能自動幫你格式化 C 源代碼，而且你也注意到了，確實是這樣，不過它 所使用的默認值和我們想要的相去甚遠 (實際上，甚至比隨機打的還要差——無數個猴子 -在 GNU emacs 里打字永遠不會創造出一個好程序) (譯註：Infinite Monkey Theorem) +在 GNU emacs 裏打字永遠不會創造出一個好程序) +*(譯註：Infinite Monkey Theorem)* 所以你要麼放棄 GNU emacs，要麼改變它讓它使用更合理的設定。要採用後一個方案， -你可以把下面這段粘貼到你的 .emacs 文件里。 +你可以把下面這段粘貼到你的 .emacs 文件裏。 -.. code-block:: none +.. code-block:: elisp (defun c-lineup-arglist-tabs-only (ignored) "Line up argument lists by tabs, not spaces" @@ -533,7 +605,7 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 (c-offsets-alist . ( (arglist-close . c-lineup-arglist-tabs-only) (arglist-cont-nonempty . - (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) (arglist-intro . +) (brace-list-intro . +) (c . c-lineup-C-comments) @@ -565,24 +637,29 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 這會讓 emacs 在 ``~/src/linux-trees`` 下的 C 源文件獲得更好的內核代碼風格。 -不過就算你嘗試讓 emacs 正確的格式化代碼失敗了，也並不意味著你失去了一切：還可 +不過就算你嘗試讓 emacs 正確的格式化代碼失敗了，也並不意味着你失去了一切：還可 以用 ``indent`` 。 不過，GNU indent 也有和 GNU emacs 一樣有問題的設定，所以你需要給它一些命令選 項。不過，這還不算太糟糕，因爲就算是 GNU indent 的作者也認同 K&R 的權威性 (GNU 的人並不是壞人，他們只是在這個問題上被嚴重的誤導了)，所以你只要給 indent 指定選項 ``-kr -i8`` (代表 ``K&R，8 字符縮進``)，或使用 ``scripts/Lindent`` -這樣就可以以最時髦的方式縮進原始碼。 +這樣就可以以最時髦的方式縮進源代碼。 -``indent`` 有很多選項，特別是重新格式化注釋的時候，你可能需要看一下它的手冊。 +``indent`` 有很多選項，特別是重新格式化註釋的時候，你可能需要看一下它的手冊。 不過記住： ``indent`` 不能修正壞的編程習慣。 +請注意，您還可以使用 ``clang-format`` 工具幫助您處理這些規則，快速自動重新格 +式化部分代碼，並審閱整個文件以發現代碼風格錯誤、打字錯誤和可能的改進。它還可 +以方便地排序 ``#include`` ，對齊變量/宏，重排文本和其他類似任務。 +詳見 Documentation/process/clang-format.rst 。 + 10) Kconfig 配置文件 ------------------------------- +-------------------- -對於遍布源碼樹的所有 Kconfig* 配置文件來說，它們縮進方式有所不同。緊挨著 -``config`` 定義的行，用一個制表符縮進，然而 help 信息的縮進則額外增加 2 個空 +對於遍佈源碼樹的所有 Kconfig* 配置文件來說，它們縮進方式有所不同。緊挨着 +``config`` 定義的行，用一個製表符縮進，然而 help 信息的縮進則額外增加 2 個空 格。舉個例子:: config AUDIT @@ -594,7 +671,7 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 logging of avc messages output). Does not do system-call auditing without CONFIG_AUDITSYSCALL. -而那些危險的功能 (比如某些文件系統的寫支持) 應該在它們的提示字符串里顯著的聲 +而那些危險的功能 (比如某些文件系統的寫支持) 應該在它們的提示字符串裏顯著的聲 明這一點:: config ADFS_FS_RW @@ -602,17 +679,17 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 depends on ADFS_FS ... -要查看配置文件的完整文檔，請看 Documentation/kbuild/kconfig-language.rst。 +要查看配置文件的完整文檔，請看 Documentation/kbuild/kconfig-language.rst 。 11) 數據結構 ------------------------------- +------------ -如果一個數據結構，在創建和銷毀它的單線執行環境之外可見，那麼它必須要有一個引 -用計數器。內核里沒有垃圾收集 (並且內核之外的垃圾收集慢且效率低下)，這意味著你 +如果一個數據結構，在創建和銷燬它的單線執行環境之外可見，那麼它必須要有一個引 +用計數器。內核裏沒有垃圾收集 (並且內核之外的垃圾收集慢且效率低下)，這意味着你 絕對需要記錄你對這種數據結構的使用情況。 -引用計數意味著你能夠避免上鎖，並且允許多個用戶並行訪問這個數據結構——而不需要 +引用計數意味着你能夠避免上鎖，並且允許多個用戶並行訪問這個數據結構——而不需要 擔心這個數據結構僅僅因爲暫時不被使用就消失了，那些用戶可能不過是沉睡了一陣或 者做了一些其他事情而已。 @@ -626,13 +703,13 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以獲得詳細信息。 mm_count)，和文件系統 (``struct super_block``: s_count 和 s_active) 中找到。 記住：如果另一個執行線索可以找到你的數據結構，但這個數據結構沒有引用計數器， -這裡幾乎肯定是一個 bug。 +這裏幾乎肯定是一個 bug。 12) 宏，枚舉和RTL ------------------------------- +----------------- -用於定義常量的宏的名字及枚舉里的標籤需要大寫。 +用於定義常量的宏的名字及枚舉裏的標籤需要大寫。 .. code-block:: c @@ -642,9 +719,9 @@ mm_count)，和文件系統 (``struct super_block``: s_count 和 s_active) 中 宏的名字請用大寫字母，不過形如函數的宏的名字可以用小寫字母。 -一般的，如果能寫成內聯函數就不要寫成像函數的宏。 +通常如果能寫成內聯函數就不要寫成像函數的宏。 -含有多個語句的宏應該被包含在一個 do-while 代碼塊里： +含有多個語句的宏應該被包含在一個 do-while 代碼塊裏： .. code-block:: c @@ -667,7 +744,7 @@ mm_count)，和文件系統 (``struct super_block``: s_count 和 s_active) 中 } while (0) **非常** 不好。它看起來像一個函數，不過卻能導致 ``調用`` 它的函數退出；不要打 -亂讀者大腦里的語法分析器。 +亂讀者大腦裏的語法分析器。 2) 依賴於一個固定名字的本地變量的宏： @@ -689,7 +766,7 @@ mm_count)，和文件系統 (``struct super_block``: s_count 和 s_active) 中 #define CONSTANT 0x4000 #define CONSTEXP (CONSTANT | 3) -5) 在宏里定義類似函數的本地變量時命名衝突： +5) 在宏裏定義類似函數的本地變量時命名衝突： .. code-block:: c @@ -700,45 +777,46 @@ mm_count)，和文件系統 (``struct super_block``: s_count 和 s_active) 中 (ret); \ }) -ret 是本地變量的通用名字 - __foo_ret 更不容易與一個已存在的變量衝突。 +ret 是本地變量的通用名字—— __foo_ret 更不容易與一個已存在的變量衝突。 -cpp 手冊對宏的講解很詳細。gcc internals 手冊也詳細講解了 RTL，內核里的彙編語 +cpp 手冊對宏的講解很詳細。gcc internals 手冊也詳細講解了 RTL，內核裏的彙編語 言經常用到它。 -13) 列印內核消息 ------------------------------- +13) 打印內核消息 +---------------- -內核開發者應該是受過良好教育的。請一定注意內核信息的拼寫，以給人以好的印象。 +內核開發者應該看起來有文化。請一定注意內核信息的拼寫，以給人良好的印象。 不要用不規範的單詞比如 ``dont``，而要用 ``do not`` 或者 ``don't`` 。保證這些信 -息簡單明了,無歧義。 +息簡單明瞭、無歧義。 內核信息不必以英文句號結束。 -在小括號里列印數字 (%d) 沒有任何價值，應該避免這樣做。 +在小括號裏打印數字 (%d) 沒有任何價值，應該避免這樣做。 - 里有一些驅動模型診斷宏，你應該使用它們，以確保信息對應於正確 + 裏有一些驅動模型診斷宏，你應該使用它們，以確保信息對應於正確 的設備和驅動，並且被標記了正確的消息級別。這些宏有：dev_err(), dev_warn(), dev_info() 等等。對於那些不和某個特定設備相關連的信息， 定義 了 pr_notice(), pr_info(), pr_warn(), pr_err() 和其他。 寫出好的調試信息可以是一個很大的挑戰；一旦你寫出後，這些信息在遠程除錯時能提 -供極大的幫助。然而列印調試信息的處理方式同列印非調試信息不同。其他 pr_XXX() -函數能無條件地列印，pr_debug() 卻不；默認情況下它不會被編譯，除非定義了 DEBUG +供極大的幫助。然而打印調試信息的處理方式同打印非調試信息不同。其他 pr_XXX() +函數能無條件地打印，pr_debug() 卻不；默認情況下它不會被編譯，除非定義了 DEBUG 或設定了 CONFIG_DYNAMIC_DEBUG。實際這同樣是爲了 dev_dbg()，一個相關約定是在一 個已經開啓了 DEBUG 時，使用 VERBOSE_DEBUG 來添加 dev_vdbg()。 -許多子系統擁有 Kconfig 調試選項來開啓 -DDEBUG 在對應的 Makefile 裡面；在其他 -情況下，特殊文件使用 #define DEBUG。當一條調試信息需要被無條件列印時，例如， +許多子系統擁有 Kconfig 調試選項來開啓對應 Makefile 裏面的 -DDEBUG；在其他 +情況下，特殊文件使用 #define DEBUG。當一條調試信息需要被無條件打印時，例如， 如果已經包含一個調試相關的 #ifdef 條件，printk(KERN_DEBUG ...) 就可被使用。 14) 分配內存 ------------------------------- +------------ 內核提供了下面的一般用途的內存分配函數： kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() 和 vzalloc()。 -請參考 API 文檔以獲取有關它們的詳細信息。 +請參考 API 文檔以獲取有關它們的詳細信息： +Documentation/translations/zh_CN/core-api/memory-allocation.rst 。 傳遞結構體大小的首選形式是這樣的： @@ -765,17 +843,19 @@ kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() 和 vzalloc()。 p = kcalloc(n, sizeof(...), ...); -兩種形式檢查分配大小 n * sizeof(...) 的溢出，如果溢出返回 NULL。 +兩種形式都會檢查分配 n * sizeof(...) 大小時內存的溢出，如果溢出返回 NULL。 +在沒有 __GFP_NOWARN 的情況下使用時，這些通用分配函數都會在失敗時發起堆棧轉儲， +因此當返回NULL時，沒有必要發出額外的失敗消息。 15) 內聯弊病 ------------------------------- +------------ 有一個常見的誤解是 ``內聯`` 是 gcc 提供的可以讓代碼運行更快的一個選項。雖然使 用內聯函數有時候是恰當的 (比如作爲一種替代宏的方式，請看第十二章)，不過很多情 況下不是這樣。inline 的過度使用會使內核變大，從而使整個系統運行速度變慢。 -因爲體積大內核會占用更多的指令高速緩存，而且會導致 pagecache 的可用內存減少。 -想像一下，一次 pagecache 未命中就會導致一次磁碟尋址，將耗時 5 毫秒。5 毫秒的 +因爲體積大內核會佔用更多的指令高速緩存，而且會導致 pagecache 的可用內存減少。 +想象一下，一次 pagecache 未命中就會導致一次磁盤尋址，將耗時 5 毫秒。5 毫秒的 時間內 CPU 能執行很多很多指令。 一個基本的原則是如果一個函數有 3 行以上，就不要把它變成內聯函數。這個原則的一 @@ -790,7 +870,7 @@ inline gcc 也可以自動使其內聯。而且其他用戶可能會要求移除 16) 函數返回值及命名 ------------------------------- +-------------------- 函數可以返回多種不同類型的值，最常見的一種是表明函數執行成功或者失敗的值。這樣 的一個值可以表示爲一個錯誤代碼整數 (-Exxx＝失敗，0＝成功) 或者一個 ``成功`` @@ -801,7 +881,7 @@ inline gcc 也可以自動使其內聯。而且其他用戶可能會要求移除 產生這種 bug，請遵循下面的慣例:: 如果函數的名字是一個動作或者強制性的命令，那麼這個函數應該返回錯誤代 - 碼整數。如果是一個判斷，那麼函數應該返回一個 "成功" 布爾值。 + 碼整數。如果是一個判斷，那麼函數應該返回一個“成功”布爾值。 比如， ``add work`` 是一個命令，所以 add_work() 在成功時返回 0，在失敗時返回 -EBUSY。類似的，因爲 ``PCI device present`` 是一個判斷，所以 pci_dev_present() @@ -810,13 +890,35 @@ inline gcc 也可以自動使其內聯。而且其他用戶可能會要求移除 所有 EXPORTed 函數都必須遵守這個慣例，所有的公共函數也都應該如此。私有 (static) 函數不需要如此，但是我們也推薦這樣做。 -返回值是實際計算結果而不是計算是否成功的標誌的函數不受此慣例的限制。一般的， +返回值是實際計算結果而不是計算是否成功的標誌的函數不受此慣例的限制。通常 他們通過返回一些正常值範圍之外的結果來表示出錯。典型的例子是返回指針的函數， 他們使用 NULL 或者 ERR_PTR 機制來報告錯誤。 +17) 使用布爾類型 +---------------- + +Linux內核布爾（bool）類型是C99 _Bool類型的別名。布爾值只能爲0或1，而對布爾的 +隱式或顯式轉換將自動將值轉換爲true或false。在使用布爾類型時 **不需要** 構造， +它會消除一類錯誤。 + +使用布爾值時，應使用true和false定義，而不是1和0。 -17) 不要重新發明內核宏 ------------------------------- +布爾函數返回類型和堆棧變量總是可以在適當的時候使用。鼓勵使用布爾來提高可讀性， +並且布爾值在存儲時通常比“int”更好。 + +如果緩存行佈局或值的大小很重要，請不要使用布爾，因爲其大小和對齊方式根據編譯 +的體系結構而不同。針對對齊和大小進行優化的結構體不應使用布爾。 + +如果一個結構體有多個true/false值，請考慮將它們合併爲具有1比特成員的位域，或使 +用適當的固定寬度類型，如u8。 + +類似地，對於函數參數，多個true/false值可以合併爲單個按位的“標誌”參數，如果調 +用點具有裸true/false常量，“標誌”參數通常是更具可讀性的替代方法。 + +總之，在結構體和參數中有限地使用布爾可以提高可讀性。 + +18) 不要重新發明內核宏 +---------------------- 頭文件 include/linux/kernel.h 包含了一些宏，你應該使用它們，而不要自己寫一些 它們的變種。比如，如果你需要計算一個數組的長度，使用這個宏 @@ -832,15 +934,15 @@ inline gcc 也可以自動使其內聯。而且其他用戶可能會要求移除 #define sizeof_field(t, f) (sizeof(((t*)0)->f)) 還有可以做嚴格的類型檢查的 min() 和 max() 宏，如果你需要可以使用它們。你可以 -自己看看那個頭文件里還定義了什麼你可以拿來用的東西，如果有定義的話，你就不應 -在你的代碼里自己重新定義。 +自己看看那個頭文件裏還定義了什麼你可以拿來用的東西，如果有定義的話，你就不應 +在你的代碼裏自己重新定義。 -18) 編輯器模式行和其他需要羅嗦的事情 --------------------------------------------------- +19) 編輯器模式行和其他需要羅嗦的事情 +------------------------------------ -有一些編輯器可以解釋嵌入在源文件里的由一些特殊標記標明的配置信息。比如，emacs -能夠解釋被標記成這樣的行： +有一些編輯器可以解釋嵌入在源文件裏的由一些特殊標記標明的配置信息。比如，emacs +能夠解析被標記成這樣的行： .. code-block:: c @@ -856,23 +958,23 @@ inline gcc 也可以自動使其內聯。而且其他用戶可能會要求移除 End: */ -Vim 能夠解釋這樣的標記： +Vim 能夠解析這樣的標記： .. code-block:: c /* vim:set sw=8 noet */ -不要在原始碼中包含任何這樣的內容。每個人都有他自己的編輯器配置，你的源文件不 +不要在源代碼中包含任何這樣的內容。每個人都有他自己的編輯器配置，你的源文件不 應該覆蓋別人的配置。這包括有關縮進和模式配置的標記。人們可以使用他們自己定製 的模式，或者使用其他可以產生正確的縮進的巧妙方法。 -19) 內聯彙編 ------------------------------- +20) 內聯彙編 +------------ -在特定架構的代碼中，你可能需要內聯彙編與 CPU 和平台相關功能連接。需要這麼做時 +在特定架構的代碼中，你可能需要內聯彙編與 CPU 和平臺相關功能連接。需要這麼做時 就不要猶豫。然而，當 C 可以完成工作時，不要平白無故地使用內聯彙編。在可能的情 -況下，你可以並且應該用 C 和硬體溝通。 +況下，你可以並且應該用 C 和硬件溝通。 請考慮去寫捆綁通用位元 (wrap common bits) 的內聯彙編的簡單輔助函數，別去重複 地寫下只有細微差異內聯彙編。記住內聯彙編可以使用 C 參數。 @@ -883,9 +985,9 @@ Vim 能夠解釋這樣的標記： 你可能需要把彙編語句標記爲 volatile，用來阻止 GCC 在沒發現任何副作用後就把它 移除了。你不必總是這樣做，儘管，這不必要的舉動會限制優化。 -在寫一個包含多條指令的單個內聯彙編語句時，把每條指令用引號分割而且各占一行， -除了最後一條指令外，在每個指令結尾加上 \n\t，讓彙編輸出時可以正確地縮進下一條 -指令： +在寫一個包含多條指令的單個內聯彙編語句時，把每條指令用引號分割而且各佔一行， +除了最後一條指令外，在每個指令結尾加上 ``\n\t`` ，讓彙編輸出時可以正確地縮進 +下一條指令： .. code-block:: c @@ -894,10 +996,10 @@ Vim 能夠解釋這樣的標記： : /* outputs */ : /* inputs */ : /* clobbers */); -20) 條件編譯 ------------------------------- +21) 條件編譯 +------------ -只要可能，就不要在 .c 文件裡面使用預處理條件 (#if, #ifdef)；這樣做讓代碼更難 +只要可能，就不要在 .c 文件裏面使用預處理條件 (#if, #ifdef)；這樣做會讓代碼更難 閱讀並且更難去跟蹤邏輯。替代方案是，在頭文件中用預處理條件提供給那些 .c 文件 使用，再給 #else 提供一個空樁 (no-op stub) 版本，然後在 .c 文件內無條件地調用 那些 (定義在頭文件內的) 函數。這樣做，編譯器會避免爲樁函數 (stub) 的調用生成 @@ -908,8 +1010,8 @@ Vim 能夠解釋這樣的標記： 條件到這個輔助函數內。 如果你有一個在特定配置中，可能變成未使用的函數或變量，編譯器會警告它定義了但 -未使用，把它標記爲 __maybe_unused 而不是將它包含在一個預處理條件中。(然而，如 -果一個函數或變量總是未使用，就直接刪除它。) +未使用，請把它標記爲 __maybe_unused 而不是將它包含在一個預處理條件中。(然而， +如果一個函數或變量總是未使用，就直接刪除它。) 在代碼中，儘可能地使用 IS_ENABLED 宏來轉化某個 Kconfig 標記爲 C 的布爾 表達式，並在一般的 C 條件中使用它： @@ -926,7 +1028,7 @@ Vim 能夠解釋這樣的標記： 不存在時，你還是必須去用 #ifdef。 在任何有意義的 #if 或 #ifdef 塊的末尾 (超過幾行的)，在 #endif 同一行的後面寫下 -註解，注釋這個條件表達式。例如： +註解，註釋這個條件表達式。例如： .. code-block:: c @@ -935,24 +1037,46 @@ Vim 能夠解釋這樣的標記： #endif /* CONFIG_SOMETHING */ -附錄 I) 參考 -------------------- +附錄 I) 參考資料 +---------------- -The C Programming Language, 第二版 +The C Programming Language, 2nd Edition 作者：Brian W. Kernighan 和 Denni M. Ritchie. Prentice Hall, Inc., 1988. -ISBN 0-13-110362-8 (軟皮), 0-13-110370-9 (硬皮). +ISBN 0-13-110362-8 (平裝), 0-13-110370-9 (精裝). + +.. note:: + + 《C程序設計語言（第2版）》 + 作者：[美] Brian W. Kernighan / [美] Dennis M. Ritchie + 譯者：徐寶文 / 李志 / 尤晉元（審校） + 出版社：機械工業出版社，2019 + ISBN：9787111617945 The Practice of Programming 作者：Brian W. Kernighan 和 Rob Pike. Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X. +.. note:: + + 《程序設計實踐》 + 作者：[美] Brian W. Kernighan / [美] Rob Pike + 出版社：機械工業出版社，2005 + ISBN：9787111091578 + + 《程序設計實踐》 + 作者：[美] Brian W. Kernighan / Rob Pike + 譯者：裘宗燕 + 出版社：機械工業出版社，2000 + ISBN：9787111075738 + GNU 手冊 - 遵循 K&R 標準和此文本 - cpp, gcc, gcc internals and indent, 都可以從 https://www.gnu.org/manual/ 找到 WG14 是 C 語言的國際標準化工作組，URL: http://www.open-std.org/JTC1/SC22/WG14/ -Kernel process/coding-style.rst，作者 greg@kroah.com 發表於 OLS 2002： +內核文檔 Documentation/process/coding-style.rst， +作者 greg@kroah.com 發表於 OLS 2002： http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/translations/zh_TW/process/development-process.rst b/Documentation/translations/zh_TW/process/development-process.rst index 45e6385647cd..f84241c5b9b1 100644 --- a/Documentation/translations/zh_TW/process/development-process.rst +++ b/Documentation/translations/zh_TW/process/development-process.rst @@ -26,5 +26,5 @@ 7.AdvancedTopics 8.Conclusion -本文檔的目的是幫助開發人員（及其經理）以最小的挫折感與開發社區合作。它試圖記錄這個社區如何以一種不熟悉Linux內核開發（或者實際上是自由軟體開發）的人可以訪問的方式工作。雖然這裡有一些技術資料，但這是一個面向過程的討論，不需要深入了解內核編程就可以理解。 +本文檔的目的是幫助開發人員（及其經理）以最小的挫折感與開發社區合作。它試圖記錄這個社區如何以一種不熟悉Linux內核開發（或者實際上是自由軟件開發）的人可以訪問的方式工作。雖然這裏有一些技術資料，但這是一個面向過程的討論，不需要深入瞭解內核編程就可以理解。 diff --git a/Documentation/translations/zh_TW/process/email-clients.rst b/Documentation/translations/zh_TW/process/email-clients.rst index 4ba543d06f3b..1bc1841c39f9 100644 --- a/Documentation/translations/zh_TW/process/email-clients.rst +++ b/Documentation/translations/zh_TW/process/email-clients.rst @@ -4,17 +4,18 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/process/email-clients.rst ` +:Original: Documentation/process/email-clients.rst -譯者:: +:譯者: + - 賈威威 Harry Wei + - 時奎亮 Alex Shi + - 吳想成 Wu XiangCheng - 中文版維護者： 賈威威 Harry Wei - 中文版翻譯者： 賈威威 Harry Wei - 時奎亮 Alex Shi - 中文版校譯者： Yinglin Luan - Xiaochen Wang - yaxinsn - Hu Haowen +:校譯: + - Yinglin Luan + - Xiaochen Wang + - yaxinsn + - Hu Haowen Linux郵件客戶端配置信息 ======================= @@ -30,30 +31,35 @@ Git 改日誌。如果工作正常，再將補丁發送到相應的郵件列表。 -普通配置 +通用配置 -------- + Linux內核補丁是通過郵件被提交的，最好把補丁作爲郵件體的內嵌文本。有些維護者 接收附件，但是附件的內容格式應該是"text/plain"。然而，附件一般是不贊成的， 因爲這會使補丁的引用部分在評論過程中變的很困難。 +同時也強烈建議在補丁或其他郵件的正文中使用純文本格式。https://useplaintext.email +有助於瞭解如何配置你喜歡的郵件客戶端，並在您還沒有首選的情況下列出一些推薦的 +客戶端。 + 用來發送Linux內核補丁的郵件客戶端在發送補丁時應該處於文本的原始狀態。例如， -他們不能改變或者刪除制表符或者空格，甚至是在每一行的開頭或者結尾。 +他們不能改變或者刪除製表符或者空格，甚至是在每一行的開頭或者結尾。 不要通過"format=flowed"模式發送補丁。這樣會引起不可預期以及有害的斷行。 不要讓你的郵件客戶端進行自動換行。這樣也會破壞你的補丁。 -郵件客戶端不能改變文本的字符集編碼方式。要發送的補丁只能是ASCII或者UTF-8編碼方式， -如果你使用UTF-8編碼方式發送郵件，那麼你將會避免一些可能發生的字符集問題。 +郵件客戶端不能改變文本的字符集編碼方式。要發送的補丁只能是ASCII或者UTF-8編碼 +方式，如果你使用UTF-8編碼方式發送郵件，那麼你將會避免一些可能發生的字符集問題。 -郵件客戶端應該形成並且保持 References: 或者 In-Reply-To: 標題，那麼 -郵件話題就不會中斷。 +郵件客戶端應該生成並且保持“References:”或者“In-Reply-To:”郵件頭，這樣郵件會話 +就不會中斷。 -複製粘帖(或者剪貼粘帖)通常不能用於補丁，因爲制表符會轉換爲空格。使用xclipboard, xclip -或者xcutsel也許可以，但是最好測試一下或者避免使用複製粘帖。 +複製粘帖(或者剪貼粘帖)通常不能用於補丁，因爲製表符會轉換爲空格。使用xclipboard, +xclip或者xcutsel也許可以，但是最好測試一下或者避免使用複製粘帖。 -不要在使用PGP/GPG署名的郵件中包含補丁。這樣會使得很多腳本不能讀取和適用於你的補丁。 -（這個問題應該是可以修復的） +不要在使用PGP/GPG簽名的郵件中包含補丁。這樣會使得很多腳本不能讀取和適用於你的 +補丁。（這個問題應該是可以修復的） 在給內核郵件列表發送補丁之前，給自己發送一個補丁是個不錯的主意，保存接收到的 郵件，將補丁用'patch'命令打上，如果成功了，再給內核郵件列表發送。 @@ -61,100 +67,135 @@ Linux內核補丁是通過郵件被提交的，最好把補丁作爲郵件體的 一些郵件客戶端提示 ------------------ -這裡給出一些詳細的MUA配置提示，可以用於給Linux內核發送補丁。這些並不意味是 -所有的軟體包配置總結。 + +這裏給出一些詳細的MUA配置提示，可以用於給Linux內核發送補丁。這些並不意味是 +所有的軟件包配置總結。 說明： -TUI = 以文本爲基礎的用戶接口 -GUI = 圖形界面用戶接口 + +- TUI = 以文本爲基礎的用戶接口 +- GUI = 圖形界面用戶接口 Alpine (TUI) -~~~~~~~~~~~~ +************ 配置選項： -在"Sending Preferences"部分： -- "Do Not Send Flowed Text"必須開啓 -- "Strip Whitespace Before Sending"必須關閉 +在 :menuselection:`Sending Preferences` 菜單： + +- :menuselection:`Do Not Send Flowed Text` 必須開啓 +- :menuselection:`Strip Whitespace Before Sending` 必須關閉 + +當寫郵件時，光標應該放在補丁會出現的地方，然後按下 :kbd:`CTRL-R` 組合鍵，使指 +定的補丁文件嵌入到郵件中。 + +Claws Mail (GUI) +**************** + +可以用，有人用它成功地發過補丁。 + +用 :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`) 或外置編輯器插入補丁。 -當寫郵件時，光標應該放在補丁會出現的地方，然後按下CTRL-R組合鍵，使指定的 -補丁文件嵌入到郵件中。 +若要在Claws編輯窗口重修改插入的補丁，需關閉 +:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` +的 `Auto wrapping` 。 Evolution (GUI) -~~~~~~~~~~~~~~~ +*************** -一些開發者成功的使用它發送補丁 +一些開發者成功的使用它發送補丁。 -當選擇郵件選項：Preformat - 從Format->Heading->Preformatted (Ctrl-7)或者工具欄 +撰寫郵件時： +從 :menuselection:`格式-->段落樣式-->預格式化` (:kbd:`CTRL-7`) +或工具欄選擇 :menuselection:`預格式化` ； 然後使用： - Insert->Text File... (Alt-n x)插入補丁文件。 +:menuselection:`插入-->文本文件...` (:kbd:`ALT-N x`) 插入補丁文件。 -你還可以"diff -Nru old.c new.c | xclip"，選擇Preformat，然後使用中間鍵進行粘帖。 +你還可以 ``diff -Nru old.c new.c | xclip`` ，選擇 :menuselection:`預格式化` ， +然後使用鼠標中鍵進行粘帖。 Kmail (GUI) -~~~~~~~~~~~ +*********** 一些開發者成功的使用它發送補丁。 -默認設置不爲HTML格式是合適的；不要啓用它。 +默認撰寫設置禁用HTML格式是合適的；不要啓用它。 + +當書寫一封郵件的時候，在選項下面不要選擇自動換行。唯一的缺點就是你在郵件中輸 +入的任何文本都不會被自動換行，因此你必須在發送補丁之前手動換行。最簡單的方法 +就是啓用自動換行來書寫郵件，然後把它保存爲草稿。一旦你在草稿中再次打開它，它 +已經全部自動換行了，那麼你的郵件雖然沒有選擇自動換行，但是還不會失去已有的自 +動換行。 -當書寫一封郵件的時候，在選項下面不要選擇自動換行。唯一的缺點就是你在郵件中輸入的任何文本 -都不會被自動換行，因此你必須在發送補丁之前手動換行。最簡單的方法就是啓用自動換行來書寫郵件， -然後把它保存爲草稿。一旦你在草稿中再次打開它，它已經全部自動換行了，那麼你的郵件雖然沒有 -選擇自動換行，但是還不會失去已有的自動換行。 +在郵件的底部，插入補丁之前，放上常用的補丁定界符：三個連字符(``---``)。 -在郵件的底部，插入補丁之前，放上常用的補丁定界符：三個連字號(---)。 +然後在 :menuselection:`信件` 菜單，選擇 :menuselection:`插入文本文件` ，接 +着選取你的補丁文件。還有一個額外的選項，你可以通過它配置你的創建新郵件工具欄， +加上 :menuselection:`插入文本文件` 圖標。 -然後在"Message"菜單條目，選擇插入文件，接著選取你的補丁文件。還有一個額外的選項，你可以 -通過它配置你的郵件建立工具欄菜單，還可以帶上"insert file"圖標。 +將編輯器窗口拉到足夠寬避免折行。對於KMail 1.13.5 (KDE 4.5.4)，它會在發送郵件 +時對編輯器窗口中顯示折行的地方自動換行。在選項菜單中取消自動換行仍不能解決。 +因此，如果你的補丁中有非常長的行，必須在發送之前把編輯器窗口拉得非常寬。 +參見：https://bugs.kde.org/show_bug.cgi?id=174034 -你可以安全地通過GPG標記附件，但是內嵌補丁最好不要使用GPG標記它們。作爲內嵌文本的簽發補丁， -當從GPG中提取7位編碼時會使他們變的更加複雜。 +你可以安全地用GPG簽名附件，但是內嵌補丁最好不要使用GPG簽名它們。作爲內嵌文本 +插入的簽名補丁將使其難以從7-bit編碼中提取。 -如果你非要以附件的形式發送補丁，那麼就右鍵點擊附件，然後選中屬性，突出"Suggest automatic -display"，這樣內嵌附件更容易讓讀者看到。 +如果你非要以附件的形式發送補丁，那麼就右鍵點擊附件，然後選擇 +:menuselection:`屬性` ，打開 :menuselection:`建議自動顯示` ，使附件內聯更容 +易讓讀者看到。 -當你要保存將要發送的內嵌文本補丁，你可以從消息列表窗格選擇包含補丁的郵件，然後右擊選擇 -"save as"。你可以使用一個沒有更改的包含補丁的郵件，如果它是以正確的形式組成。當你正真在它 -自己的窗口之下察看，那時沒有選項可以保存郵件--已經有一個這樣的bug被匯報到了kmail的bugzilla -並且希望這將會被處理。郵件是以只針對某個用戶可讀寫的權限被保存的，所以如果你想把郵件複製到其他地方， -你不得不把他們的權限改爲組或者整體可讀。 +當你要保存將要發送的內嵌文本補丁，你可以從消息列表窗格選擇包含補丁的郵件，然 +後右鍵選擇 :menuselection:`另存爲` 。如果整個電子郵件的組成正確，您可直接將 +其作爲補丁使用。電子郵件以當前用戶可讀寫權限保存，因此您必須 ``chmod`` ，以 +使其在複製到別處時用戶組和其他人可讀。 Lotus Notes (GUI) -~~~~~~~~~~~~~~~~~ +***************** 不要使用它。 +IBM Verse (Web GUI) +******************* + +同上條。 + Mutt (TUI) -~~~~~~~~~~ +********** -很多Linux開發人員使用mutt客戶端，所以證明它肯定工作的非常漂亮。 +很多Linux開發人員使用mutt客戶端，這證明它肯定工作得非常漂亮。 -Mutt不自帶編輯器，所以不管你使用什麼編輯器都不應該帶有自動斷行。大多數編輯器都帶有 -一個"insert file"選項，它可以通過不改變文件內容的方式插入文件。 +Mutt不自帶編輯器，所以不管你使用什麼編輯器，不自動斷行就行。大多數編輯器都有 +:menuselection:`插入文件` 選項，它可以在不改變文件內容的情況下插入文件。 + +用 ``vim`` 作爲mutt的編輯器:: -'vim'作爲mutt的編輯器： set editor="vi" - 如果使用xclip，敲入以下命令 +如果使用xclip，敲入以下命令:: + :set paste - 按中鍵之前或者shift-insert或者使用 + +然後再按中鍵或者shift-insert或者使用:: + :r filename -如果想要把補丁作爲內嵌文本。 -(a)ttach工作的很好，不帶有"set paste"。 +把補丁插入爲內嵌文本。 +在未設置 ``set paste`` 時(a)ttach工作的很好。 你可以通過 ``git format-patch`` 生成補丁，然後用 Mutt發送它們:: - $ mutt -H 0001-some-bug-fix.patch + $ mutt -H 0001-some-bug-fix.patch 配置選項： + 它應該以默認設置的形式工作。 -然而，把"send_charset"設置爲"us-ascii::utf-8"也是一個不錯的主意。 +然而，把 ``send_charset`` 設置一下也是一個不錯的主意:: + + set send_charset="us-ascii:utf-8" -Mutt 是高度可配置的。 這裡是個使用mutt通過 Gmail 發送的補丁的最小配置:: +Mutt 是高度可配置的。 這裏是個使用mutt通過 Gmail 發送的補丁的最小配置:: # .muttrc # ================ IMAP ==================== @@ -181,72 +222,108 @@ Mutt 是高度可配置的。 這裡是個使用mutt通過 Gmail 發送的補丁 set from = "username@gmail.com" set use_from = yes -Mutt文檔含有更多信息: +Mutt文檔含有更多信息： - http://dev.mutt.org/trac/wiki/UseCases/Gmail + https://gitlab.com/muttmua/mutt/-/wikis/UseCases/Gmail - http://dev.mutt.org/doc/manual.html + http://www.mutt.org/doc/manual/ Pine (TUI) -~~~~~~~~~~ +********** Pine過去有一些空格刪減問題，但是這些現在應該都被修復了。 -如果可以，請使用alpine(pine的繼承者) +如果可以，請使用alpine（pine的繼承者）。 配置選項： -- 最近的版本需要消除流程文本 -- "no-strip-whitespace-before-send"選項也是需要的。 + +- 最近的版本需要 ``quell-flowed-text`` +- ``no-strip-whitespace-before-send`` 選項也是需要的。 Sylpheed (GUI) -~~~~~~~~~~~~~~ +************** - 內嵌文本可以很好的工作（或者使用附件）。 - 允許使用外部的編輯器。 -- 對於目錄較多時非常慢。 +- 收件箱較多時非常慢。 - 如果通過non-SSL連接，無法使用TLS SMTP授權。 -- 在組成窗口中有一個很有用的ruler bar。 -- 給地址本中添加地址就不會正確的了解顯示名。 +- 撰寫窗口的標尺很有用。 +- 將地址添加到通訊簿時無法正確理解顯示的名稱。 Thunderbird (GUI) -~~~~~~~~~~~~~~~~~ +***************** + +Thunderbird是Outlook的克隆版本，它很容易損壞文本，但也有一些方法強制修正。 + +在完成修改後（包括安裝擴展），您需要重新啓動Thunderbird。 + +- 允許使用外部編輯器： + + 使用Thunderbird發補丁最簡單的方法是使用擴展來打開您最喜歡的外部編輯器。 + + 下面是一些能夠做到這一點的擴展樣例。 + + - “External Editor Revived” + + https://github.com/Frederick888/external-editor-revived + + https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/ + + 它需要安裝“本地消息主機（native messaging host）”。 + 參見以下文檔: + https://github.com/Frederick888/external-editor-revived/wiki + + - “External Editor” + + https://github.com/exteditor/exteditor + + 下載並安裝此擴展，然後打開 :menuselection:`新建消息` 窗口, 用 + :menuselection:`查看-->工具欄-->自定義...` 給它增加一個按鈕，直接點擊此 + 按鈕即可使用外置編輯器。 + + 請注意，“External Editor”要求你的編輯器不能fork，換句話說，編輯器必須在 + 關閉前不返回。你可能需要傳遞額外的參數或修改編輯器設置。最值得注意的是， + 如果您使用的是gvim，那麼您必須將 :menuselection:`external editor` 設置的 + 編輯器字段設置爲 ``/usr/bin/gvim --nofork"`` （假設可執行文件在 + ``/usr/bin`` ），以傳遞 ``-f`` 參數。如果您正在使用其他編輯器，請閱讀其 + 手冊瞭解如何處理。 -默認情況下，thunderbird很容易損壞文本，但是還有一些方法可以強制它變得更好。 +若要修正內部編輯器，請執行以下操作： -- 在用戶帳號設置里，組成和尋址，不要選擇"Compose messages in HTML format"。 +- 修改你的Thunderbird設置，不要使用 ``format=flowed`` ！ + 回到主窗口，按照 + :menuselection:`主菜單-->首選項-->常規-->配置編輯器...` + 打開Thunderbird的配置編輯器。 -- 編輯你的Thunderbird配置設置來使它不要拆行使用：user_pref("mailnews.wraplength", 0); + - 將 ``mailnews.send_plaintext_flowed`` 設爲 ``false`` -- 編輯你的Thunderbird配置設置，使它不要使用"format=flowed"格式：user_pref("mailnews. - send_plaintext_flowed", false); + - 將 ``mailnews.wraplength`` 從 ``72`` 改爲 ``0`` -- 你需要使Thunderbird變爲預先格式方式： - 如果默認情況下你書寫的是HTML格式，那不是很難。僅僅從標題欄的下拉框中選擇"Preformat"格式。 - 如果默認情況下你書寫的是文本格式，你不得把它改爲HTML格式（僅僅作爲一次性的）來書寫新的消息， - 然後強制使它回到文本格式，否則它就會拆行。要實現它，在寫信的圖標上使用shift鍵來使它變爲HTML - 格式，然後標題欄的下拉框中選擇"Preformat"格式。 +- 不要寫HTML郵件！ + 回到主窗口，打開 + :menuselection:`主菜單-->賬戶設置-->你的@郵件.地址-->通訊錄/編寫&地址簿` ， + 關掉 ``以HTML格式編寫消息`` 。 -- 允許使用外部的編輯器： - 針對Thunderbird打補丁最簡單的方法就是使用一個"external editor"擴展，然後使用你最喜歡的 - $EDITOR來讀取或者合併補丁到文本中。要實現它，可以下載並且安裝這個擴展，然後添加一個使用它的 - 按鍵View->Toolbars->Customize...最後當你書寫信息的時候僅僅點擊它就可以了。 +- 只用純文本格式查看郵件！ + 回到主窗口， :menuselection:`主菜單-->查看-->消息體爲-->純文本` ！ TkRat (GUI) -~~~~~~~~~~~ +*********** 可以使用它。使用"Insert file..."或者外部的編輯器。 Gmail (Web GUI) -~~~~~~~~~~~~~~~ +*************** 不要使用它發送補丁。 -Gmail網頁客戶端自動地把制表符轉換爲空格。 +Gmail網頁客戶端自動地把製表符轉換爲空格。 -雖然制表符轉換爲空格問題可以被外部編輯器解決，同時它還會使用回車換行把每行拆分爲78個字符。 +雖然製表符轉換爲空格問題可以被外部編輯器解決，但它同時還會使用回車換行把每行 +拆分爲78個字符。 -另一個問題是Gmail還會把任何不是ASCII的字符的信息改爲base64編碼。它把東西變的像歐洲人的名字。 +另一個問題是Gmail還會把任何含有非ASCII的字符的消息改用base64編碼，如歐洲人的 +名字。 - ### diff --git a/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst b/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst index fbde3e26eda5..f67a3f11e70f 100644 --- a/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst +++ b/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst @@ -6,27 +6,27 @@ :Translator: Alex Shi Hu Haowen -被限制的硬體問題 +被限制的硬件問題 ================ 範圍 ---- -導致安全問題的硬體問題與只影響Linux內核的純軟體錯誤是不同的安全錯誤類別。 +導致安全問題的硬件問題與隻影響Linux內核的純軟件錯誤是不同的安全錯誤類別。 -必須區別對待諸如熔毀(Meltdown)、Spectre、L1TF等硬體問題，因爲它們通常會影響 -所有作業系統（「OS」），因此需要在不同的OS供應商、發行版、硬體供應商和其他各方 -之間進行協調。對於某些問題，軟體緩解可能依賴於微碼或固件更新，這需要進一步的 +必須區別對待諸如熔燬(Meltdown)、Spectre、L1TF等硬件問題，因爲它們通常會影響 +所有操作系統（“OS”），因此需要在不同的OS供應商、發行版、硬件供應商和其他各方 +之間進行協調。對於某些問題，軟件緩解可能依賴於微碼或固件更新，這需要進一步的 協調。 -.. _tw_Contact: +.. _zh_Contact: 接觸 ---- -Linux內核硬體安全小組獨立於普通的Linux內核安全小組。 +Linux內核硬件安全小組獨立於普通的Linux內核安全小組。 -該小組只負責協調被限制的硬體安全問題。Linux內核中純軟體安全漏洞的報告不由該 +該小組只負責協調被限制的硬件安全問題。Linux內核中純軟件安全漏洞的報告不由該 小組處理，報告者將被引導至常規Linux內核安全小組(:ref:`Documentation/admin-guide/ `)聯繫。 @@ -37,13 +37,13 @@ Linux內核硬體安全小組獨立於普通的Linux內核安全小組。 者的PGP密鑰或S/MIME證書籤名。該列表的PGP密鑰和S/MIME證書可從 https://www.kernel.org/.... 獲得。 -雖然硬體安全問題通常由受影響的硬體供應商處理，但我們歡迎發現潛在硬體缺陷的研究 +雖然硬件安全問題通常由受影響的硬件供應商處理，但我們歡迎發現潛在硬件缺陷的研究 人員或個人與我們聯繫。 -硬體安全官 +硬件安全官 ^^^^^^^^^^ -目前的硬體安全官小組: +目前的硬件安全官小組: - Linus Torvalds（Linux基金會院士） - Greg Kroah Hartman（Linux基金會院士） @@ -62,50 +62,50 @@ Linux基金會目前的IT基礎設施安全總監是 Konstantin Ryabitsev。 保密協議 -------- -Linux內核硬體安全小組不是正式的機構，因此無法簽訂任何保密協議。核心社區意識到 +Linux內核硬件安全小組不是正式的機構，因此無法簽訂任何保密協議。核心社區意識到 這些問題的敏感性，並提供了一份諒解備忘錄。 諒解備忘錄 ---------- -Linux內核社區深刻理解在不同作業系統供應商、發行商、硬體供應商和其他各方之間 -進行協調時，保持硬體安全問題處於限制狀態的要求。 +Linux內核社區深刻理解在不同操作系統供應商、發行商、硬件供應商和其他各方之間 +進行協調時，保持硬件安全問題處於限制狀態的要求。 -Linux內核社區在過去已經成功地處理了硬體安全問題，並且有必要的機制允許在限制 +Linux內核社區在過去已經成功地處理了硬件安全問題，並且有必要的機制允許在限制 限制下進行符合社區的開發。 -Linux內核社區有一個專門的硬體安全小組負責初始聯繫，並監督在限制規則下處理 +Linux內核社區有一個專門的硬件安全小組負責初始聯繫，並監督在限制規則下處理 此類問題的過程。 -硬體安全小組確定開發人員（領域專家），他們將組成特定問題的初始響應小組。最初 +硬件安全小組確定開發人員（領域專家），他們將組成特定問題的初始響應小組。最初 的響應小組可以引入更多的開發人員（領域專家）以最佳的技術方式解決這個問題。 所有相關開發商承諾遵守限制規定，並對收到的信息保密。違反承諾將導致立即從當前 -問題中排除，並從所有相關郵件列表中刪除。此外，硬體安全小組還將把違反者排除在 +問題中排除，並從所有相關郵件列表中刪除。此外，硬件安全小組還將把違反者排除在 未來的問題之外。這一後果的影響在我們社區是一種非常有效的威懾。如果發生違規 -情況，硬體安全小組將立即通知相關方。如果您或任何人發現潛在的違規行爲，請立即 -向硬體安全人員報告。 +情況，硬件安全小組將立即通知相關方。如果您或任何人發現潛在的違規行爲，請立即 +向硬件安全人員報告。 流程 ^^^^ -由於Linux內核開發的全球分布式特性，面對面的會議幾乎不可能解決硬體安全問題。 +由於Linux內核開發的全球分佈式特性，面對面的會議幾乎不可能解決硬件安全問題。 由於時區和其他因素，電話會議很難協調，只能在絕對必要時使用。加密電子郵件已被 證明是解決此類問題的最有效和最安全的通信方法。 開始披露 """""""" -披露內容首先通過電子郵件聯繫Linux內核硬體安全小組。此初始聯繫人應包含問題的 -描述和任何已知受影響硬體的列表。如果您的組織製造或分發受影響的硬體，我們建議 -您也考慮哪些其他硬體可能會受到影響。 +披露內容首先通過電子郵件聯繫Linux內核硬件安全小組。此初始聯繫人應包含問題的 +描述和任何已知受影響硬件的列表。如果您的組織製造或分發受影響的硬件，我們建議 +您也考慮哪些其他硬件可能會受到影響。 -硬體安全小組將提供一個特定於事件的加密郵件列表，用於與報告者進行初步討論、 +硬件安全小組將提供一個特定於事件的加密郵件列表，用於與報告者進行初步討論、 進一步披露和協調。 -硬體安全小組將向披露方提供一份開發人員（領域專家）名單，在與開發人員確認他們 +硬件安全小組將向披露方提供一份開發人員（領域專家）名單，在與開發人員確認他們 將遵守本諒解備忘錄和文件化流程後，應首先告知開發人員有關該問題的信息。這些開發 -人員組成初始響應小組，並在初始接觸後負責處理問題。硬體安全小組支持響應小組， +人員組成初始響應小組，並在初始接觸後負責處理問題。硬件安全小組支持響應小組， 但不一定參與緩解開發過程。 雖然個別開發人員可能通過其僱主受到保密協議的保護，但他們不能以Linux內核開發 @@ -113,7 +113,7 @@ Linux內核社區有一個專門的硬體安全小組負責初始聯繫，並監 披露方應提供已經或應該被告知該問題的所有其他實體的聯繫人名單。這有幾個目的: - - 披露的實體列表允許跨行業通信，例如其他作業系統供應商、硬體供應商等。 + - 披露的實體列表允許跨行業通信，例如其他操作系統供應商、硬件供應商等。 - 可聯繫已披露的實體，指定應參與緩解措施開發的專家。 @@ -133,10 +133,10 @@ Linux內核社區有一個專門的硬體安全小組負責初始聯繫，並監 初始響應小組設置加密郵件列表，或在適當的情況下重新修改現有郵件列表。 -使用郵件列表接近於正常的Linux開發過程，並且在過去已經成功地用於爲各種硬體安全 +使用郵件列表接近於正常的Linux開發過程，並且在過去已經成功地用於爲各種硬件安全 問題開發緩解措施。 -郵件列表的操作方式與正常的Linux開發相同。發布、討論和審查修補程序，如果同意， +郵件列表的操作方式與正常的Linux開發相同。發佈、討論和審查修補程序，如果同意， 則應用於非公共git存儲庫，參與開發人員只能通過安全連接訪問該存儲庫。存儲庫包含 針對主線內核的主開發分支，並根據需要爲穩定的內核版本提供向後移植分支。 @@ -155,9 +155,9 @@ Linux內核社區有一個專門的硬體安全小組負責初始聯繫，並監 """""""" 有關各方將協商限制結束的日期和時間。此時，準備好的緩解措施集成到相關的內核樹中 -並發布。 +併發布。 -雖然我們理解硬體安全問題需要協調限制時間，但限制時間應限制在所有有關各方制定、 +雖然我們理解硬件安全問題需要協調限制時間，但限制時間應限制在所有有關各方制定、 測試和準備緩解措施所需的最短時間內。人爲地延長限制時間以滿足會議討論日期或其他 非技術原因，會給相關的開發人員和響應小組帶來了更多的工作和負擔，因爲補丁需要 保持最新，以便跟蹤正在進行的上游內核開發，這可能會造成衝突的更改。 @@ -165,7 +165,7 @@ Linux內核社區有一個專門的硬體安全小組負責初始聯繫，並監 CVE分配 """"""" -硬體安全小組和初始響應小組都不分配CVE，開發過程也不需要CVE。如果CVE是由披露方 +硬件安全小組和初始響應小組都不分配CVE，開發過程也不需要CVE。如果CVE是由披露方 提供的，則可用於文檔中。 流程專使 @@ -196,22 +196,22 @@ CVE分配 Google Kees Cook ============= ======================================================== -如果要將您的組織添加到專使名單中，請與硬體安全小組聯繫。被提名的專使必須完全 +如果要將您的組織添加到專使名單中，請與硬件安全小組聯繫。被提名的專使必須完全 理解和支持我們的過程，並且在Linux內核社區中很容易聯繫。 加密郵件列表 ------------ 我們使用加密郵件列表進行通信。這些列表的工作原理是，發送到列表的電子郵件使用 -列表的PGP密鑰或列表的/MIME證書進行加密。郵件列表軟體對電子郵件進行解密，並 +列表的PGP密鑰或列表的/MIME證書進行加密。郵件列表軟件對電子郵件進行解密，並 使用訂閱者的PGP密鑰或S/MIME證書爲每個訂閱者分別對其進行重新加密。有關郵件列表 -軟體和用於確保列表安全和數據保護的設置的詳細信息，請訪問: +軟件和用於確保列表安全和數據保護的設置的詳細信息，請訪問: https://www.kernel.org/.... 關鍵點 ^^^^^^ -初次接觸見 :ref:`tw_Contact`. 對於特定於事件的郵件列表，密鑰和S/MIME證書通過 +初次接觸見 :ref:`zh_Contact`. 對於特定於事件的郵件列表，密鑰和S/MIME證書通過 特定列表發送的電子郵件傳遞給訂閱者。 訂閱事件特定列表 @@ -220,8 +220,8 @@ https://www.kernel.org/.... 訂閱由響應小組處理。希望參與通信的披露方將潛在訂戶的列表發送給響應組，以便 響應組可以驗證訂閱請求。 -每個訂戶都需要通過電子郵件向響應小組發送訂閱請求。電子郵件必須使用訂閱伺服器 -的PGP密鑰或S/MIME證書籤名。如果使用PGP密鑰，則必須從公鑰伺服器獲得該密鑰， +每個訂戶都需要通過電子郵件向響應小組發送訂閱請求。電子郵件必須使用訂閱服務器 +的PGP密鑰或S/MIME證書籤名。如果使用PGP密鑰，則必須從公鑰服務器獲得該密鑰， 並且理想情況下該密鑰連接到Linux內核的PGP信任網。另請參見: https://www.kernel.org/signature.html. diff --git a/Documentation/translations/zh_TW/process/howto.rst b/Documentation/translations/zh_TW/process/howto.rst index ea2f468d3e58..ae19d1eda30f 100644 --- a/Documentation/translations/zh_TW/process/howto.rst +++ b/Documentation/translations/zh_TW/process/howto.rst @@ -1,6 +1,4 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. _tw_process_howto: +.. _tw_process_howto: .. include:: ../disclaimer-zh_TW.rst @@ -31,8 +29,8 @@ 入門 ---- -你想了解如何成爲一名Linux內核開發者？或者老闆吩咐你「給這個設備寫個Linux -驅動程序」？這篇文章的目的就是教會你達成這些目標的全部訣竅，它將描述你需 +你想了解如何成爲一名Linux內核開發者？或者老闆吩咐你“給這個設備寫個Linux +驅動程序”？這篇文章的目的就是教會你達成這些目標的全部訣竅，它將描述你需 要經過的流程以及給出如何同內核社區合作的一些提示。它還將試圖解釋內核社區 爲何這樣運作。 @@ -52,11 +50,11 @@ Linux內核使用GNU C和GNU工具鏈開發。雖然它遵循ISO C11標準，但 標準中沒有定義的擴展。內核是自給自足的C環境，不依賴於標準C庫的支持，所以 並不支持C標準中的部分定義。比如long long類型的大數除法和浮點運算就不允許 使用。有時候確實很難弄清楚內核對工具鏈的要求和它所使用的擴展，不幸的是目 -前還沒有明確的參考資料可以解釋它們。請查閱gcc信息頁（使用「info gcc」命令 +前還沒有明確的參考資料可以解釋它們。請查閱gcc信息頁（使用“info gcc”命令 顯示）獲得一些這方面信息。 請記住你是在學習怎麼和已經存在的開發社區打交道。它由一羣形形色色的人組成， -他們對代碼、風格和過程有著很高的標準。這些標準是在長期實踐中總結出來的， +他們對代碼、風格和過程有着很高的標準。這些標準是在長期實踐中總結出來的， 適應於地理上分散的大型開發團隊。它們已經被很好得整理成檔，建議你在開發 之前儘可能多的學習這些標準，而不要期望別人來適應你或者你公司的行爲方式。 @@ -64,21 +62,21 @@ Linux內核使用GNU C和GNU工具鏈開發。雖然它遵循ISO C11標準，但 法律問題 -------- -Linux內核原始碼都是在GPL（通用公共許可證）的保護下發布的。要了解這種許可 -的細節請查看原始碼主目錄下的COPYING文件。Linux內核許可準則和如何使用 +Linux內核源代碼都是在GPL（通用公共許可證）的保護下發布的。要了解這種許可 +的細節請查看源代碼主目錄下的COPYING文件。Linux內核許可準則和如何使用 `SPDX ` 標誌符說明在這個文件中 -:ref:`Documentation/translations/zh_TW/process/license-rules.rst ` +:ref:`Documentation/translations/zh_CN/process/license-rules.rst ` 如果你對它還有更深入問題請聯繫律師，而不要在Linux內核郵件組上提問。因爲 -郵件組裡的人並不是律師，不要期望他們的話有法律效力。 +郵件組裏的人並不是律師，不要期望他們的話有法律效力。 -對於GPL的常見問題和解答，請訪問以下連結： +對於GPL的常見問題和解答，請訪問以下鏈接： https://www.gnu.org/licenses/gpl-faq.html 文檔 ---- -Linux內核代碼中包含有大量的文檔。這些文檔對於學習如何與內核社區互動有著 +Linux內核代碼中包含有大量的文檔。這些文檔對於學習如何與內核社區互動有着 不可估量的價值。當一個新的功能被加入內核，最好把解釋如何使用這個功能的文 檔也放進內核。當內核的改動導致面向用戶空間的接口發生變化時，最好將相關信 息或手冊頁(manpages)的補丁發到mtk.manpages@gmail.com，以向手冊頁(manpages) @@ -86,19 +84,19 @@ Linux內核代碼中包含有大量的文檔。這些文檔對於學習如何與 以下是內核代碼中需要閱讀的文檔： :ref:`Documentation/admin-guide/README.rst ` - 文件簡要介紹了Linux內核的背景，並且描述了如何配置和編譯內核。內核的 - 新用戶應該從這裡開始。 + 文件簡要介紹了Linux內核的背景，並且描述瞭如何配置和編譯內核。內核的 + 新用戶應該從這裏開始。 :ref:`Documentation/process/changes.rst ` - 文件給出了用來編譯和使用內核所需要的最小軟體包列表。 + 文件給出了用來編譯和使用內核所需要的最小軟件包列表。 - :ref:`Documentation/translations/zh_TW/process/coding-style.rst ` + :ref:`Documentation/translations/zh_CN/process/coding-style.rst ` 描述Linux內核的代碼風格和理由。所有新代碼需要遵守這篇文檔中定義的規 - 范。大多數維護者只會接收符合規定的補丁，很多人也只會幫忙檢查符合風格 + 範。大多數維護者只會接收符合規定的補丁，很多人也只會幫忙檢查符合風格 的代碼。 - :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst ` + :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst ` 這兩份文檔明確描述如何創建和發送補丁，其中包括（但不僅限於)： - 郵件內容 @@ -106,7 +104,7 @@ Linux內核代碼中包含有大量的文檔。這些文檔對於學習如何與 - 選擇收件人 遵守這些規定並不能保證提交成功（因爲所有補丁需要通過嚴格的內容和風格 - 審查），但是忽視他們幾乎就意味著失敗。 + 審查），但是忽視他們幾乎就意味着失敗。 其他關於如何正確地生成補丁的優秀文檔包括： "The Perfect Patch" @@ -117,29 +115,29 @@ Linux內核代碼中包含有大量的文檔。這些文檔對於學習如何與 https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html - :ref:`Documentation/translations/zh_TW/process/stable-api-nonsense.rst ` + :ref:`Documentation/translations/zh_CN/process/stable-api-nonsense.rst ` 論證內核爲什麼特意不包括穩定的內核內部API，也就是說不包括像這樣的特 性： - 子系統中間層（爲了兼容性？） - - 在不同作業系統間易於移植的驅動程序 + - 在不同操作系統間易於移植的驅動程序 - 減緩（甚至阻止）內核代碼的快速變化 - 這篇文檔對於理解Linux的開發哲學至關重要。對於將開發平台從其他操作系 + 這篇文檔對於理解Linux的開發哲學至關重要。對於將開發平臺從其他操作系 統轉移到Linux的人來說也很重要。 :ref:`Documentation/process/security-bugs.rst ` 如果你認爲自己發現了Linux內核的安全性問題，請根據這篇文檔中的步驟來 提醒其他內核開發者並幫助解決這個問題。 - :ref:`Documentation/translations/zh_TW/process/management-style.rst ` + :ref:`Documentation/translations/zh_CN/process/management-style.rst ` 描述內核維護者的工作方法及其共有特點。這對於剛剛接觸內核開發（或者對 它感到好奇）的人來說很重要，因爲它解釋了很多對於內核維護者獨特行爲的 普遍誤解與迷惑。 :ref:`Documentation/process/stable-kernel-rules.rst ` - 解釋了穩定版內核發布的規則，以及如何將改動放入這些版本的步驟。 + 解釋了穩定版內核發佈的規則，以及如何將改動放入這些版本的步驟。 :ref:`Documentation/process/kernel-docs.rst ` 有助於內核開發的外部文檔列表。如果你在內核自帶的文檔中沒有找到你想找 @@ -163,7 +161,7 @@ ReST格式的文檔會生成在 Documentation/output. 目錄中。 如何成爲內核開發者 ------------------ -如果你對Linux內核開發一無所知，你應該訪問「Linux內核新手」計劃： +如果你對Linux內核開發一無所知，你應該訪問“Linux內核新手”計劃： https://kernelnewbies.org @@ -171,12 +169,12 @@ ReST格式的文檔會生成在 Documentation/output. 目錄中。 查找已往的郵件，確認是否有人已經回答過相同的問題）。它還擁有一個可以獲得 實時反饋的IRC聊天頻道，以及大量對於學習Linux內核開發相當有幫助的文檔。 -網站簡要介紹了原始碼組織結構、子系統劃分以及目前正在進行的項目（包括內核 +網站簡要介紹了源代碼組織結構、子系統劃分以及目前正在進行的項目（包括內核 中的和單獨維護的）。它還提供了一些基本的幫助信息，比如如何編譯內核和打補 丁。 -如果你想加入內核開發社區並協助完成一些任務，卻找不到從哪裡開始，可以訪問 -「Linux內核房管員」計劃： +如果你想加入內核開發社區並協助完成一些任務，卻找不到從哪裏開始，可以訪問 +“Linux內核房管員”計劃： https://kernelnewbies.org/KernelJanitors @@ -186,9 +184,9 @@ ReST格式的文檔會生成在 Documentation/output. 目錄中。 向性的指點。 在真正動手修改內核代碼之前，理解要修改的代碼如何運作是必需的。要達到這個 -目的，沒什麼辦法比直接讀代碼更有效了（大多數花招都會有相應的注釋），而且 -一些特製的工具還可以提供幫助。例如，「Linux代碼交叉引用」項目就是一個值得 -特別推薦的幫助工具，它將原始碼顯示在有編目和索引的網頁上。其中一個更新及 +目的，沒什麼辦法比直接讀代碼更有效了（大多數花招都會有相應的註釋），而且 +一些特製的工具還可以提供幫助。例如，“Linux代碼交叉引用”項目就是一個值得 +特別推薦的幫助工具，它將源代碼顯示在有編目和索引的網頁上。其中一個更新及 時的內核源碼庫，可以通過以下地址訪問： https://elixir.bootlin.com/ @@ -197,7 +195,7 @@ ReST格式的文檔會生成在 Documentation/output. 目錄中。 開發流程 -------- -目前Linux內核開發流程包括幾個「主內核分支」和很多子系統相關的內核分支。這 +目前Linux內核開發流程包括幾個“主內核分支”和很多子系統相關的內核分支。這 些分支包括： - Linus 的內核源碼樹 @@ -211,40 +209,40 @@ ReST格式的文檔會生成在 Documentation/output. 目錄中。 主線樹是由Linus Torvalds 維護的。你可以在https://kernel.org 網站或者代碼 庫中下找到它。它的開發遵循以下步驟： - - 每當一個新版本的內核被發布，爲期兩周的集成窗口將被打開。在這段時間裡 + - 每當一個新版本的內核被髮布，爲期兩週的集成窗口將被打開。在這段時間裏 維護者可以向Linus提交大段的修改，通常這些修改已經被放到-mm內核中幾個 星期了。提交大量修改的首選方式是使用git工具（內核的代碼版本管理工具 ，更多的信息可以在 https://git-scm.com/ 獲取），不過使用普通補丁也是 可以的。 - - 兩個星期以後-rc1版本內核發布。之後只有不包含可能影響整個內核穩定性的 - 新功能的補丁才可能被接受。請注意一個全新的驅動程序（或者文件系統）有 + - 兩個星期以後-rc1版本內核發佈。之後只有不包含可能影響整個內核穩定性的 + 新功能的補丁纔可能被接受。請注意一個全新的驅動程序（或者文件系統）有 可能在-rc1後被接受是因爲這樣的修改完全獨立，不會影響其他的代碼，所以 沒有造成內核退步的風險。在-rc1以後也可以用git向Linus提交補丁，不過所 - 有的補丁需要同時被發送到相應的公衆郵件列表以徵詢意見。 - - 當Linus認爲當前的git源碼樹已經達到一個合理健全的狀態足以發布供人測試 - 時，一個新的-rc版本就會被發布。計劃是每周都發布新的-rc版本。 + 有的補丁需要同時被髮送到相應的公衆郵件列表以徵詢意見。 + - 當Linus認爲當前的git源碼樹已經達到一個合理健全的狀態足以發佈供人測試 + 時，一個新的-rc版本就會被髮布。計劃是每週都發布新的-rc版本。 - 這個過程一直持續下去直到內核被認爲達到足夠穩定的狀態，持續時間大概是 6個星期。 -關於內核發布，值得一提的是Andrew Morton在linux-kernel郵件列表中如是說： - 「沒有人知道新內核何時會被發布，因爲發布是根據已知bug的情況來決定 - 的，而不是根據一個事先制定好的時間表。」 +關於內核發佈，值得一提的是Andrew Morton在linux-kernel郵件列表中如是說： + “沒有人知道新內核何時會被髮布，因爲發佈是根據已知bug的情況來決定 + 的，而不是根據一個事先制定好的時間表。” 子系統特定樹 ------------ -各種內核子系統的維護者——以及許多內核子系統開發人員——在原始碼庫中公開了他們 +各種內核子系統的維護者——以及許多內核子系統開發人員——在源代碼庫中公開了他們 當前的開發狀態。這樣，其他人就可以看到內核的不同區域發生了什麼。在開發速度 很快的領域，可能會要求開發人員將提交的內容建立在這樣的子系統內核樹上，這樣 就避免了提交與其他已經進行的工作之間的衝突。 -這些存儲庫中的大多數都是Git樹，但是也有其他的scm在使用，或者補丁隊列被發布 +這些存儲庫中的大多數都是Git樹，但是也有其他的scm在使用，或者補丁隊列被髮布 爲Quilt系列。這些子系統存儲庫的地址列在MAINTAINERS文件中。其中許多可以在 https://git.kernel.org/上瀏覽。 在將一個建議的補丁提交到這樣的子系統樹之前，需要對它進行審查，審查主要發生 在郵件列表上（請參見下面相應的部分）。對於幾個內核子系統，這個審查過程是通 -過工具補丁跟蹤的。Patchwork提供了一個Web界面，顯示補丁發布、對補丁的任何評 +過工具補丁跟蹤的。Patchwork提供了一個Web界面，顯示補丁發佈、對補丁的任何評 論或修訂，維護人員可以將補丁標記爲正在審查、接受或拒絕。大多數補丁網站都列 在 https://patchwork.kernel.org/ @@ -254,10 +252,10 @@ Linux-next 集成測試樹 在將子系統樹的更新合併到主線樹之前，需要對它們進行集成測試。爲此，存在一個 特殊的測試存儲庫，其中幾乎每天都會提取所有子系統樹： - https://git.kernel.org/？p=linux/kernel/git/next/linux-next.git + https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git 通過這種方式，Linux-next 對下一個合併階段將進入主線內核的內容給出了一個概要 -展望。非常歡冒險的測試者運行測試Linux-next。 +展望。非常歡迎冒險的測試者運行測試Linux-next。 多個主要版本的穩定版內核樹 ----------------------------------- @@ -267,11 +265,11 @@ Linux-next 集成測試樹 這種版本的內核適用於那些期望獲得最新的穩定版內核並且不想參與測試開發版或 者實驗版的用戶。 -穩定版內核樹版本由「穩定版」小組（郵件地址）維護，一般 -隔周發布新版本。 +穩定版內核樹版本由“穩定版”小組（郵件地址）維護，一般 +隔週發佈新版本。 內核源碼中的 :ref:`Documentation/process/stable-kernel-rules.rst ` -文件具體描述了可被穩定版內核接受的修改類型以及發布的流程。 +文件具體描述了可被穩定版內核接受的修改類型以及發佈的流程。 報告bug @@ -283,7 +281,7 @@ bugzilla.kernel.org是Linux內核開發者們用來跟蹤內核Bug的網站。 http://test.kernel.org/bugzilla/faq.html 內核源碼主目錄中的:ref:`admin-guide/reporting-bugs.rst ` -文件里有一個很好的模板。它指導用戶如何報告可能的內核bug以及需要提供哪些信息 +文件裏有一個很好的模板。它指導用戶如何報告可能的內核bug以及需要提供哪些信息 來幫助內核開發者們找到問題的根源。 @@ -302,11 +300,11 @@ bugzilla.kernel.org是Linux內核開發者們用來跟蹤內核Bug的網站。 -------- 正如上面的文檔所描述，大多數的骨幹內核開發者都加入了Linux Kernel郵件列 -表。如何訂閱和退訂列表的細節可以在這裡找到： +表。如何訂閱和退訂列表的細節可以在這裏找到： http://vger.kernel.org/vger-lists.html#linux-kernel -網上很多地方都有這個郵件列表的存檔(archive)。可以使用搜尋引擎來找到這些 +網上很多地方都有這個郵件列表的存檔(archive)。可以使用搜索引擎來找到這些 存檔。比如： https://lore.kernel.org/lkml/ @@ -317,11 +315,11 @@ bugzilla.kernel.org是Linux內核開發者們用來跟蹤內核Bug的網站。 大多數內核子系統也有自己獨立的郵件列表來協調各自的開發工作。從 MAINTAINERS文件中可以找到不同話題對應的郵件列表。 -很多郵件列表架設在kernel.org伺服器上。這些列表的信息可以在這裡找到： +很多郵件列表架設在kernel.org服務器上。這些列表的信息可以在這裏找到： http://vger.kernel.org/vger-lists.html -在使用這些郵件列表時，請記住保持良好的行爲習慣。下面的連結提供了與這些列 +在使用這些郵件列表時，請記住保持良好的行爲習慣。下面的鏈接提供了與這些列 表（或任何其它郵件列表）交流的一些簡單規則，雖然內容有點濫竽充數。 http://www.albion.com/netiquette/ @@ -331,14 +329,14 @@ MAINTAINERS文件中可以找到不同話題對應的郵件列表。 一封郵件接收兩次（一封來自發送者一封來自郵件列表），而不要試圖通過添加一 些奇特的郵件頭來解決這個問題，人們不會喜歡的。 -記住保留你所回復內容的上下文和源頭。在你回覆郵件的頂部保留「某某某說到……」 +記住保留你所回覆內容的上下文和源頭。在你回覆郵件的頂部保留“某某某說到……” 這幾行。將你的評論加在被引用的段落之間而不要放在郵件的頂部。 如果你在郵件中附帶補丁，請確認它們是可以直接閱讀的純文本（如 -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst ` +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst ` 文檔中所述）。內核開發者們不希望遇到附件或者被壓縮了的補丁。只有這樣才能 保證他們可以直接評論你的每行代碼。請確保你使用的郵件發送程序不會修改空格 -和制表符。一個防範性的測試方法是先將郵件發送給自己，然後自己嘗試是否可以 +和製表符。一個防範性的測試方法是先將郵件發送給自己，然後自己嘗試是否可以 順利地打上收到的補丁。如果測試不成功，請調整或者更換你的郵件發送程序直到 它正確工作爲止。 @@ -359,7 +357,7 @@ MAINTAINERS文件中可以找到不同話題對應的郵件列表。 要記住，這些是把補丁放進內核的正常情況。你必須學會聽取對補丁的批評和評論， 從技術層面評估它們，然後要麼重寫你的補丁要麼簡明扼要地論證修改是不必要 -的。如果你發的郵件沒有得到任何回應，請過幾天後再試一次，因爲有時信件會湮 +的。如果你發的郵件沒有得到任何回應，請過幾天后再試一次，因爲有時信件會湮 沒在茫茫信海中。 你不應該做的事情： @@ -369,13 +367,13 @@ MAINTAINERS文件中可以找到不同話題對應的郵件列表。 - 忽略別人的評論 - 沒有按照別人的要求做任何修改就重新提交 -在一個努力追尋最好技術方案的社區里，對於一個補丁有多少好處總會有不同的見 -解。你必須要抱著合作的態度，願意改變自己的觀點來適應內核的風格。或者至少 -願意去證明你的想法是有價值的。記住，犯錯誤是允許的，只要你願意朝著正確的 +在一個努力追尋最好技術方案的社區裏，對於一個補丁有多少好處總會有不同的見 +解。你必須要抱着合作的態度，願意改變自己的觀點來適應內核的風格。或者至少 +願意去證明你的想法是有價值的。記住，犯錯誤是允許的，只要你願意朝着正確的 方案去努力。 如果你的第一個補丁換來的是一堆修改建議，這是很正常的。這並不代表你的補丁 -不會被接受，也不意味著有人和你作對。你只需要改正所有提出的問題然後重新發 +不會被接受，也不意味着有人和你作對。你只需要改正所有提出的問題然後重新發 送你的補丁。 內核社區和公司文化的差異 @@ -383,7 +381,7 @@ MAINTAINERS文件中可以找到不同話題對應的郵件列表。 內核社區的工作模式同大多數傳統公司開發隊伍的工作模式並不相同。下面這些例 子，可以幫助你避免某些可能發生問題： -用這些話介紹你的修改提案會有好處： +用這些話介紹你的修改提案會有好處：（在任何時候你都不應該用中文寫提案） - 它同時解決了多個問題 - 它刪除了2000行代碼 @@ -398,15 +396,15 @@ MAINTAINERS文件中可以找到不同話題對應的郵件列表。 - 我做這行已經20年了，所以…… - 爲了我們公司賺錢考慮必須這麼做 - 這是我們的企業產品線所需要的 - - 這裡是描述我觀點的1000頁設計文檔 + - 這裏是描述我觀點的1000頁設計文檔 - 這是一個5000行的補丁用來…… - 我重寫了現在亂七八糟的代碼，這就是…… - 我被規定了最後期限，所以這個補丁需要立刻被接受 -另外一個內核社區與大部分傳統公司的軟體開發隊伍不同的地方是無法面對面地交 +另外一個內核社區與大部分傳統公司的軟件開發隊伍不同的地方是無法面對面地交 流。使用電子郵件和IRC聊天工具做爲主要溝通工具的一個好處是性別和種族歧視 將會更少。Linux內核的工作環境更能接受婦女和少數族羣，因爲每個人在別人眼 -里只是一個郵件地址。國際化也幫助了公平的實現，因爲你無法通過姓名來判斷人 +裏只是一個郵件地址。國際化也幫助了公平的實現，因爲你無法通過姓名來判斷人 的性別。男人有可能叫李麗，女人也有可能叫王剛。大多數在Linux內核上工作過 並表達過看法的女性對在linux上工作的經歷都給出了正面的評價。 @@ -437,10 +435,10 @@ Linux內核社區並不喜歡一下接收大段的代碼。修改需要被恰當 2）不光發送小的補丁很重要，在提交之前重新編排、化簡（或者僅僅重新排列） 補丁也是很重要的。 -這裡有內核開發者Al Viro打的一個比方： - 「想像一個老師正在給學生批改數學作業。老師並不希望看到學生爲了得 +這裏有內核開發者Al Viro打的一個比方： + “想象一個老師正在給學生批改數學作業。老師並不希望看到學生爲了得 到正確解法所進行的嘗試和產生的錯誤。他希望看到的是最乾淨最優雅的 - 解答。好學生了解這點，絕不會把最終解決之前的中間方案提交上去。」 + 解答。好學生了解這點，絕不會把最終解決之前的中間方案提交上去。” 內核開發也是這樣。維護者和評審者不希望看到一個人在解決問題時的思 考過程。他們只希望看到簡單和優雅的解決方案。 @@ -450,20 +448,20 @@ Linux內核社區並不喜歡一下接收大段的代碼。修改需要被恰當 保證修改分成很多小塊，這樣在整個項目都準備好被包含進內核之前，其中的一部 分可能會先被接收。 -必須了解這樣做是不可接受的：試圖將未完成的工作提交進內核，然後再找時間修 -復。 +你必須明白這麼做是無法令人接受的：試圖將不完整的代碼提交進內核，然後再找 +時間修復。 證明修改的必要性 ---------------- -除了將補丁拆成小塊，很重要的一點是讓Linux社區了解他們爲什麼需要這樣修改。 +除了將補丁拆成小塊，很重要的一點是讓Linux社區瞭解他們爲什麼需要這樣修改。 你必須證明新功能是有人需要的並且是有用的。 記錄修改 -------- -當你發送補丁的時候，需要特別留意郵件正文的內容。因爲這裡的信息將會做爲補 +當你發送補丁的時候，需要特別留意郵件正文的內容。因爲這裏的信息將會做爲補 丁的修改記錄(ChangeLog)，會被一直保留以備大家查閱。它需要完全地描述補丁， 包括： @@ -472,19 +470,19 @@ Linux內核社區並不喜歡一下接收大段的代碼。修改需要被恰當 - 實現細節 - 測試結果 -想了解它具體應該看起來像什麼，請查閱以下文檔中的「ChangeLog」章節： - 「The Perfect Patch」 +想了解它具體應該看起來像什麼，請查閱以下文檔中的“ChangeLog”章節： + “The Perfect Patch” https://www.ozlabs.org/~akpm/stuff/tpp.txt -這些事情有時候做起來很難。要在任何方面都做到完美可能需要好幾年時間。這是 -一個持續提高的過程，它需要大量的耐心和決心。只要不放棄，你一定可以做到。 +這些事情有時候做起來很難。想要在任何方面都做到完美可能需要好幾年時間。這 +是一個持續提高的過程，它需要大量的耐心和決心。只要不放棄，你一定可以做到。 很多人已經做到了，而他們都曾經和現在的你站在同樣的起點上。 感謝 ---- -感謝Paolo Ciarrocchi允許「開發流程」部分基於他所寫的文章 +感謝Paolo Ciarrocchi允許“開發流程”部分基於他所寫的文章 (http://www.kerneltravel.net/newbie/2.6-development_process)，感謝Randy Dunlap和Gerrit Huizenga完善了應該說和不該說的列表。感謝Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, Vojtech Pavlik, Jan Kara, Josh Boyer, diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst index c5c59b4fd595..27520f69c8e4 100644 --- a/Documentation/translations/zh_TW/process/index.rst +++ b/Documentation/translations/zh_TW/process/index.rst @@ -13,11 +13,12 @@ .. _tw_process_index: +======================== 與Linux 內核社區一起工作 ======================== 你想成爲Linux內核開發人員嗎？歡迎之至！在學習許多關於內核的技術知識的同時， -了解我們社區的工作方式也很重要。閱讀這些文檔可以讓您以更輕鬆的、麻煩更少的 +瞭解我們社區的工作方式也很重要。閱讀這些文檔可以讓您以更輕鬆的、麻煩更少的 方式將更改合併到內核。 以下是每位開發人員都應閱讀的基本指南： @@ -49,7 +50,7 @@ management-style embargoed-hardware-issues -這些是一些總體性技術指南，由於不大好分類而放在這裡： +這些是一些總體性技術指南，由於不大好分類而放在這裏： .. toctree:: :maxdepth: 1 diff --git a/Documentation/translations/zh_TW/process/kernel-driver-statement.rst b/Documentation/translations/zh_TW/process/kernel-driver-statement.rst index 8f225379b12c..025f6013b521 100644 --- a/Documentation/translations/zh_TW/process/kernel-driver-statement.rst +++ b/Documentation/translations/zh_TW/process/kernel-driver-statement.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 -.. _zh_process_statement_driver: +.. _tw_process_statement_driver: .. include:: ../disclaimer-zh_TW.rst diff --git a/Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst b/Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst index 99e21d22800d..7b24b567cd73 100644 --- a/Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst +++ b/Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst @@ -1,5 +1,3 @@ -.. SPDX-License-Identifier: GPL-2.0 - .. _tw_process_statement_kernel: .. include:: ../disclaimer-zh_TW.rst @@ -11,11 +9,11 @@ Linux 內核執行聲明 ------------------ -作爲Linux內核的開發人員，我們對如何使用我們的軟體以及如何實施軟體許可證有著 -濃厚的興趣。遵守GPL-2.0的互惠共享義務對我們軟體和社區的長期可持續性至關重要。 +作爲Linux內核的開發人員，我們對如何使用我們的軟件以及如何實施軟件許可證有着 +濃厚的興趣。遵守GPL-2.0的互惠共享義務對我們軟件和社區的長期可持續性至關重要。 雖然有權強制執行對我們社區的貢獻中的單獨版權權益，但我們有共同的利益，即確保 -個人強制執行行動的方式有利於我們的社區，不會對我們軟體生態系統的健康和增長 +個人強制執行行動的方式有利於我們的社區，不會對我們軟件生態系統的健康和增長 產生意外的負面影響。爲了阻止無益的執法行動，我們同意代表我們自己和我們版權 利益的任何繼承人對Linux內核用戶作出以下符合我們開發社區最大利益的承諾: @@ -32,9 +30,9 @@ Linux 內核執行聲明 從該版權所有者處收到違反本許可的通知（對於任何作品），並且您在收到通知 後的30天內糾正違規行爲。則您從特定版權所有者處獲得的許可將永久恢復. -我們提供這些保證的目的是鼓勵更多地使用該軟體。我們希望公司和個人使用、修改和 -分發此軟體。我們希望以公開和透明的方式與用戶合作，以消除我們對法規遵從性或強制 -執行的任何不確定性，這些不確定性可能會限制我們軟體的採用。我們將法律行動視爲 +我們提供這些保證的目的是鼓勵更多地使用該軟件。我們希望公司和個人使用、修改和 +分發此軟件。我們希望以公開和透明的方式與用戶合作，以消除我們對法規遵從性或強制 +執行的任何不確定性，這些不確定性可能會限制我們軟件的採用。我們將法律行動視爲 最後手段，只有在其他社區努力未能解決這一問題時才採取行動。 最後，一旦一個不合規問題得到解決，我們希望用戶會感到歡迎，加入我們爲之努力的 diff --git a/Documentation/translations/zh_TW/process/license-rules.rst b/Documentation/translations/zh_TW/process/license-rules.rst index ad2b80f97123..d165dafece80 100644 --- a/Documentation/translations/zh_TW/process/license-rules.rst +++ b/Documentation/translations/zh_TW/process/license-rules.rst @@ -1,7 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 -.. SPDX-License-Identifier: GPL-2.0 - .. include:: ../disclaimer-zh_TW.rst :Original: :ref:`Documentation/process/license-rules.rst ` @@ -17,10 +15,10 @@ Linux內核根據LICENSES/preferred/GPL-2.0中提供的GNU通用公共許可證 （GPL-2.0）的條款提供，並在LICENSES/exceptions/Linux-syscall-note中顯式 描述了例外的系統調用，如COPYING文件中所述。 -此文檔文件提供了如何對每個源文件進行注釋以使其許可證清晰明確的說明。 +此文檔文件提供瞭如何對每個源文件進行註釋以使其許可證清晰明確的說明。 它不會取代內核的許可證。 -內核原始碼作爲一個整體適用於COPYING文件中描述的許可證，但是單個源文件可以 +內核源代碼作爲一個整體適用於COPYING文件中描述的許可證，但是單個源文件可以 具有不同的與GPL-20兼容的許可證:: GPL-1.0+ : GNU通用公共許可證v1.0或更高版本 @@ -34,18 +32,18 @@ Linux內核根據LICENSES/preferred/GPL-2.0中提供的GNU通用公共許可證 MIT等許可。 用戶空間API（UAPI）頭文件描述了用戶空間程序與內核的接口，這是一種特殊情況。 -根據內核COPYING文件中的注釋，syscall接口是一個明確的邊界，它不會將GPL要求 -擴展到任何使用它與內核通信的軟體。由於UAPI頭文件必須包含在創建在Linux內核 +根據內核COPYING文件中的註釋，syscall接口是一個明確的邊界，它不會將GPL要求 +擴展到任何使用它與內核通信的軟件。由於UAPI頭文件必須包含在創建在Linux內核 上運行的可執行文件的任何源文件中，因此此例外必須記錄在特別的許可證表述中。 -表達源文件許可證的常用方法是將匹配的樣板文本添加到文件的頂部注釋中。由於 -格式，拼寫錯誤等，這些「樣板」很難通過那些在上下文中使用的驗證許可證合規性 +表達源文件許可證的常用方法是將匹配的樣板文本添加到文件的頂部註釋中。由於 +格式，拼寫錯誤等，這些“樣板”很難通過那些在上下文中使用的驗證許可證合規性 的工具。 -樣板文本的替代方法是在每個源文件中使用軟體包數據交換（SPDX）許可證標識符。 +樣板文本的替代方法是在每個源文件中使用軟件包數據交換（SPDX）許可證標識符。 SPDX許可證標識符是機器可解析的，並且是用於提供文件內容的許可證的精確縮寫。 SPDX許可證標識符由Linux 基金會的SPDX 工作組管理，並得到了整個行業，工具 -供應商和法律團隊的合作夥伴的一致同意。有關詳細信息，請參閱 +供應商和法律團隊的合作伙伴的一致同意。有關詳細信息，請參閱 https://spdx.org/ Linux內核需要所有源文件中的精確SPDX標識符。內核中使用的有效標識符在 @@ -58,7 +56,7 @@ https://spdx.org/licenses/ 上的官方SPDX許可證列表中檢索，並附帶 1.安置: -   內核文件中的SPDX許可證標識符應添加到可包含注釋的文件中的第一行。對於大多 +   內核文件中的SPDX許可證標識符應添加到可包含註釋的文件中的第一行。對於大多 數文件，這是第一行，除了那些在第一行中需要'#!PATH_TO_INTERPRETER'的腳本。 對於這些腳本，SPDX標識符進入第二行。 @@ -66,7 +64,7 @@ https://spdx.org/licenses/ 上的官方SPDX許可證列表中檢索，並附帶 2. 風格: - SPDX許可證標識符以注釋的形式添加。注釋樣式取決於文件類型:: + SPDX許可證標識符以註釋的形式添加。註釋樣式取決於文件類型:: C source: // SPDX-License-Identifier: C header: /* SPDX-License-Identifier: */ @@ -75,20 +73,20 @@ https://spdx.org/licenses/ 上的官方SPDX許可證列表中檢索，並附帶 .rst: .. SPDX-License-Identifier: .dts{i}: // SPDX-License-Identifier: - 如果特定工具無法處理標準注釋樣式，則應使用工具接受的相應注釋機制。這是在 - C 頭文件中使用「/\*\*/」樣式注釋的原因。過去在使用生成的.lds文件中觀察到 - 構建被破壞，其中'ld'無法解析C++注釋。現在已經解決了這個問題，但仍然有較 - 舊的彙編程序工具無法處理C++樣式的注釋。 + 如果特定工具無法處理標準註釋樣式，則應使用工具接受的相應註釋機制。這是在 + C 頭文件中使用“/\*\*/”樣式註釋的原因。過去在使用生成的.lds文件中觀察到 + 構建被破壞，其中'ld'無法解析C++註釋。現在已經解決了這個問題，但仍然有較 + 舊的彙編程序工具無法處理C++樣式的註釋。 | 3. 句法: 是SPDX許可證列表中的SPDX短格式許可證標識符，或者在許可 - 證例外適用時由「WITH」分隔的兩個SPDX短格式許可證標識符的組合。當應用多個許 - 可證時，表達式由分隔子表達式的關鍵字「AND」，「OR」組成，並由「（」，「）」包圍。 + 證例外適用時由“WITH”分隔的兩個SPDX短格式許可證標識符的組合。當應用多個許 + 可證時，表達式由分隔子表達式的關鍵字“AND”，“OR”組成，並由“（”，“）”包圍。 - 帶有「或更高」選項的[L]GPL等許可證的許可證標識符通過使用「+」來表示「或更高」 + 帶有“或更高”選項的[L]GPL等許可證的許可證標識符通過使用“+”來表示“或更高” 選項來構建。:: // SPDX-License-Identifier: GPL-2.0+ @@ -230,7 +228,7 @@ https://spdx.org/licenses/ 上的官方SPDX許可證列表中檢索，並附帶 元標籤: - 「其他」許可證的元標籤要求與 `優先許可`_ 的要求相同。 + “其他”許可證的元標籤要求與 `優先許可`_ 的要求相同。 文件格式示例:: @@ -267,8 +265,8 @@ https://spdx.org/licenses/ 上的官方SPDX許可證列表中檢索，並附帶 LICENSES/exceptions/GCC-exception-2.0 - 包含GCC'連結例外'，它允許獨立於其許可證的任何二進位文件與標記有此例外的 - 文件的編譯版本連結。這是從GPL不兼容原始碼創建可運行的可執行文件所必需的。 + 包含GCC'鏈接例外'，它允許獨立於其許可證的任何二進制文件與標記有此例外的 + 文件的編譯版本鏈接。這是從GPL不兼容源代碼創建可運行的可執行文件所必需的。 _`例外元標記`: @@ -333,11 +331,11 @@ https://spdx.org/licenses/ 上的官方SPDX許可證列表中檢索，並附帶 _`模塊許可` ----------------- - 可加載內核模塊還需要MODULE_LICENSE（）標記。此標記既不替代正確的原始碼 + 可加載內核模塊還需要MODULE_LICENSE（）標記。此標記既不替代正確的源代碼 許可證信息（SPDX-License-Identifier），也不以任何方式表示或確定提供模塊 - 原始碼的確切許可證。 + 源代碼的確切許可證。 - 此標記的唯一目的是提供足夠的信息，該模塊是否是自由軟體或者是內核模塊加 + 此標記的唯一目的是提供足夠的信息，該模塊是否是自由軟件或者是內核模塊加 載器和用戶空間工具的專有模塊。 MODULE_LICENSE（）的有效許可證字符串是: @@ -365,9 +363,9 @@ _`模塊許可` 只能通過相應的源文件中的許可證信息來確定。 "Proprietary" 該模塊屬於專有許可。此字符串僅用於專有的第三 - 方模塊，不能用於在內核樹中具有原始碼的模塊。 - 以這種方式標記的模塊在加載時會使用'P'標記汙 - 染內核，並且內核模塊加載器拒絕將這些模塊連結 + 方模塊，不能用於在內核樹中具有源代碼的模塊。 + 以這種方式標記的模塊在加載時會使用'P'標記污 + 染內核，並且內核模塊加載器拒絕將這些模塊鏈接 到使用EXPORT_SYMBOL_GPL（）導出的符號。 ============================= ============================================= diff --git a/Documentation/translations/zh_TW/process/management-style.rst b/Documentation/translations/zh_TW/process/management-style.rst index dce248470063..2d373f71e976 100644 --- a/Documentation/translations/zh_TW/process/management-style.rst +++ b/Documentation/translations/zh_TW/process/management-style.rst @@ -16,22 +16,22 @@ Linux內核管理風格 主要是爲了避免反覆回答 [#cnf1]_ 相同（或類似）的問題。 管理風格是非常個人化的，比簡單的編碼風格規則更難以量化，因此本文檔可能與實 -際情況有關，也可能與實際情況無關。起初它是一個玩笑，但這並不意味著它可能不 +際情況有關，也可能與實際情況無關。起初它是一個玩笑，但這並不意味着它可能不 是真的。你得自己決定。 -順便說一句，在談到「核心管理者」時，主要是技術負責人，而不是在公司內部進行傳 -統管理的人。如果你簽署了採購訂單或者對你的團隊的預算有任何了解，你幾乎肯定 +順便說一句，在談到“核心管理者”時，主要是技術負責人，而不是在公司內部進行傳 +統管理的人。如果你簽署了採購訂單或者對你的團隊的預算有任何瞭解，你幾乎肯定 不是一個核心管理者。這些建議可能適用於您，也可能不適用於您。 -首先，我建議你購買「高效人的七個習慣」，而不是閱讀它。燒了它，這是一個偉大的 +首先，我建議你購買“高效人的七個習慣”，而不是閱讀它。燒了它，這是一個偉大的 象徵性姿態。 .. [#cnf1] 本文件並不是通過回答問題，而是通過讓提問者痛苦地明白，我們不知道 答案是什麼。 -不管怎樣，這裡是： +不管怎樣，這裏是： -.. _tw_decisions: +.. _cn_decisions: 1）決策 ------- @@ -39,14 +39,14 @@ Linux內核管理風格 每個人都認爲管理者做決定，而且決策很重要。決定越大越痛苦，管理者就必須越高級。 這很明顯，但事實並非如此。 -遊戲的名字是 **避免** 做出決定。尤其是，如果有人告訴你「選擇（a）或（b）， -我們真的需要你來做決定」，你就是陷入麻煩的管理者。你管理的人比你更了解細節， +最重要的是 **避免** 做出決定。尤其是，如果有人告訴你“選擇（a）或（b）， +我們真的需要你來做決定”，你就是陷入麻煩的管理者。你管理的人比你更瞭解細節， 所以如果他們來找你做技術決策，你完蛋了。你顯然沒有能力爲他們做這個決定。 -（推論：如果你管理的人不比你更了解細節，你也會被搞砸，儘管原因完全不同。 +（推論：如果你管理的人不比你更瞭解細節，你也會被搞砸，儘管原因完全不同。 也就是說，你的工作是錯的，他們應該管理你的才智） -所以遊戲的名字是 **避免** 做出決定，至少是那些大而痛苦的決定。做一些小的 +所以最重要的是 **避免** 做出決定，至少是那些大而痛苦的決定。做一些小的 和非結果性的決定是很好的，並且使您看起來好像知道自己在做什麼，所以內核管理者 需要做的是將那些大的和痛苦的決定變成那些沒有人真正關心的小事情。 @@ -61,7 +61,7 @@ Linux內核管理風格 逃離的角落。走投無路的老鼠可能很危險——走投無路的管理者真可憐。 事實證明，由於沒有人會愚蠢到讓內核管理者承擔巨大的財政責任，所以通常很容易 -回溯。既然你不可能浪費掉你無法償還的巨額資金，你唯一可以回溯的就是技術決策， +回溯。既然你不可能浪費掉你無法償還的鉅額資金，你唯一可以回溯的就是技術決策， 而回溯很容易：只要告訴大家你是個不稱職的傻瓜，說對不起，然後撤銷你去年讓別 人所做的毫無價值的工作。突然間，你一年前做的決定不在是一個重大的決定，因爲 它很容易被推翻。 @@ -72,7 +72,7 @@ Linux內核管理風格 確實很難。 - 如果有人告訴你，你去年所做的工作終究是不值得的，那麼對那些可憐的低級工 程師來說也是很困難的，雖然實際的 **工作** 很容易刪除，但你可能已經不可 - 挽回地失去了工程師的信任。記住：「不可撤銷」是我們一開始就試圖避免的， + 挽回地失去了工程師的信任。記住：“不可撤銷”是我們一開始就試圖避免的， 而你的決定終究是一個重大的決定。 令人欣慰的是，這兩個原因都可以通過預先承認你沒有任何線索，提前告訴人們你的 @@ -80,19 +80,19 @@ Linux內核管理風格 的權利，並讓人們 **意識** 到這一點。當你 **還沒有** 做過真正愚蠢的事情的時 候，承認自己是愚蠢的要容易得多。 -然後，當它真的被證明是愚蠢的時候，人們就轉動他們的眼珠說「哎呀，下次不要了」。 +然後，當它真的被證明是愚蠢的時候，人們就轉動他們的眼珠說“哎呀，下次不要了”。 這種對不稱職的先發制人的承認，也可能使真正做這項工作的人也會三思是否值得做。 畢竟，如果他們不確定這是否是一個好主意，你肯定不應該通過向他們保證他們所做 的工作將會進入（內核）鼓勵他們。在他們開始一項巨大的努力之前，至少讓他們三 思而後行。 -記住：他們最好比你更了解細節，而且他們通常認爲他們對每件事都有答案。作爲一 +記住：他們最好比你更瞭解細節，而且他們通常認爲他們對每件事都有答案。作爲一 個管理者，你能做的最好的事情不是灌輸自信，而是對他們所做的事情進行健康的批 判性思考。 -順便說一句，另一種避免做出決定的方法是看起來很可憐的抱怨 「我們不能兩者兼 -得嗎？」 相信我，它是有效的。如果不清楚哪種方法更好，他們最終會弄清楚的。 +順便說一句，另一種避免做出決定的方法是看起來很可憐的抱怨 “我們不能兩者兼 +得嗎？” 相信我，它是有效的。如果不清楚哪種方法更好，他們最終會弄清楚的。 最終的答案可能是兩個團隊都會因爲這種情況而感到沮喪，以至於他們放棄了。 這聽起來像是一個失敗，但這通常是一個跡象，表明兩個項目都有問題，而參與其中 @@ -102,7 +102,7 @@ Linux內核管理風格 2）人 ----- -大多數人都是白癡，做一名管理者意味著你必須處理好這件事，也許更重要的是, +大多數人都是白癡，做一名管理者意味着你必須處理好這件事，也許更重要的是, **他們** 必須處理好你。 事實證明，雖然很容易糾正技術錯誤，但不容易糾正人格障礙。你只能和他們的和 @@ -110,16 +110,16 @@ Linux內核管理風格 但是，爲了做好作爲內核管理者的準備，最好記住不要燒掉任何橋樑，不要轟炸任何 無辜的村民，也不要疏遠太多的內核開發人員。事實證明，疏遠人是相當容易的，而 -親近一個疏遠的人是很難的。因此，「疏遠」立即屬於「不可逆」的範疇，並根據 -:ref:`tw_decisions` 成爲絕不可以做的事情。 +親近一個疏遠的人是很難的。因此，“疏遠”立即屬於“不可逆”的範疇，並根據 +:ref:`cn_decisions` 成爲絕不可以做的事情。 -這裡只有幾個簡單的規則： +這裏只有幾個簡單的規則： (1) 不要叫人笨蛋（至少不要在公共場合） (2) 學習如何在忘記規則(1)時道歉 -問題在於 #1 很容易去做，因爲你可以用數百萬種不同的方式說「你是一個笨蛋」 [#cnf2]_ -有時甚至沒有意識到，而且幾乎總是帶著一種白熱化的信念，認爲你是對的。 +問題在於 #1 很容易去做，因爲你可以用數百萬種不同的方式說“你是一個笨蛋” [#cnf2]_ +有時甚至沒有意識到，而且幾乎總是帶着一種白熱化的信念，認爲你是對的。 你越確信自己是對的（讓我們面對現實吧，你可以把幾乎所有人都稱爲壞人，而且你 經常是對的），事後道歉就越難。 @@ -127,12 +127,12 @@ Linux內核管理風格 要解決此問題，您實際上只有兩個選項： - 非常擅長道歉 - - 把「愛」均勻地散開，沒有人會真正感覺到自己被不公平地瞄準了。讓它有足夠的 + - 把“愛”均勻地散開，沒有人會真正感覺到自己被不公平地瞄準了。讓它有足夠的 創造性，他們甚至可能會覺得好笑。 選擇永遠保持禮貌是不存在的。沒有人會相信一個如此明顯地隱藏了他們真實性格的人。 -.. [#cnf2] 保羅·西蒙演唱了「離開愛人的50種方法」，因爲坦率地說，「告訴開發者 +.. [#cnf2] 保羅·西蒙演唱了“離開愛人的50種方法”，因爲坦率地說，“告訴開發者 他們是D*CKHEAD" 的100萬種方法都無法確認。但我確信他已經這麼想了。 3）人2 - 好人 @@ -148,8 +148,8 @@ Linux內核管理風格 特別是，他們能夠爲你做決定，這就是遊戲的全部內容。 所以當你發現一個比你聰明的人時，就順其自然吧。你的管理職責在很大程度上變成 -了「聽起來像是個好主意——去嘗試吧」，或者「聽起來不錯，但是XXX呢？」「。第二個版 -本尤其是一個很好的方法，要麼學習一些關於「XXX」的新東西，要麼通過指出一些聰明 +了“聽起來像是個好主意——去嘗試吧”，或者“聽起來不錯，但是XXX呢？”“。第二個版 +本尤其是一個很好的方法，要麼學習一些關於“XXX”的新東西，要麼通過指出一些聰明 人沒有想到的東西來顯得更具管理性。無論哪種情況，你都會贏。 要注意的一件事是認識到一個領域的偉大不一定會轉化爲其他領域。所以你可能會向 @@ -172,22 +172,22 @@ Linux內核管理風格 他們也可能是能夠解決問題的人。因爲，讓我們面對現實吧，肯定不是你。 承擔責任也是你首先成爲管理者的原因。這是讓人們信任你，讓你獲得潛在的榮耀的 -一部分，因爲你就是那個會說「我搞砸了」的人。如果你已經遵循了以前的規則，你現 +一部分，因爲你就是那個會說“我搞砸了”的人。如果你已經遵循了以前的規則，你現 在已經很擅長說了。 5）應避免的事情 --------------- -有一件事人們甚至比被稱爲「笨蛋」更討厭，那就是在一個神聖的聲音中被稱爲「笨蛋」。 +有一件事人們甚至比被稱爲“笨蛋”更討厭，那就是在一個神聖的聲音中被稱爲“笨蛋”。 第一個你可以道歉，第二個你不會真正得到機會。即使你做得很好，他們也可能不再 傾聽。 -我們都認爲自己比別人強，這意味著當別人裝腔作勢時，這會讓我們很惱火。你也許 +我們都認爲自己比別人強，這意味着當別人裝腔作勢時，這會讓我們很惱火。你也許 在道德和智力上比你周圍的每個人都優越，但不要試圖太明顯，除非你真的打算激怒 某人 [#cnf3]_ 同樣，不要對事情太客氣或太微妙。禮貌很容易落得落花流水，把問題隱藏起來， -正如他們所說，「在網際網路上，沒人能聽到你的含蓄。」用一個鈍器把這一點錘進去， +正如他們所說，“在互聯網上，沒人能聽到你的含蓄。”用一個鈍器把這一點錘進去， 因爲你不能真的依靠別人來獲得你的觀點。 一些幽默可以幫助緩和直率和道德化。過度到荒謬的地步，可以灌輸一個觀點，而不 @@ -203,8 +203,8 @@ Linux內核管理風格 既然你的主要責任似乎是爲別人的錯誤承擔責任，並且讓別人痛苦地明白你是不稱職 的，那麼顯而易見的問題之一就變成了爲什麼首先要這樣做。 -首先，雖然你可能會或可能不會聽到十幾歲女孩（或男孩，讓我們不要在這裡評判或 -性別歧視）敲你的更衣室門，你會得到一個巨大的個人成就感爲「負責」。別介意你真 +首先，雖然你可能會或可能不會聽到十幾歲女孩（或男孩，讓我們不要在這裏評判或 +性別歧視）敲你的更衣室門，你會得到一個巨大的個人成就感爲“負責”。別介意你真 的在領導別人，你要跟上別人，儘可能快地追趕他們。每個人都會認爲你是負責人。 如果你可以做到這個， 這是個偉大的工作！ diff --git a/Documentation/translations/zh_TW/process/stable-api-nonsense.rst b/Documentation/translations/zh_TW/process/stable-api-nonsense.rst index 22caa5b8d422..d2c2e90661da 100644 --- a/Documentation/translations/zh_TW/process/stable-api-nonsense.rst +++ b/Documentation/translations/zh_TW/process/stable-api-nonsense.rst @@ -17,45 +17,45 @@ Linux 內核驅動接口 ================== -寫作本文檔的目的，是爲了解釋爲什麼Linux既沒有二進位內核接口，也沒有穩定 -的內核接口。這裡所說的內核接口，是指內核里的接口，而不是內核和用戶空間 -的接口。內核到用戶空間的接口，是提供給應用程式使用的系統調用，系統調用 -在歷史上幾乎沒有過變化，將來也不會有變化。我有一些老應用程式是在0.9版本 -或者更早版本的內核上編譯的，在使用2.6版本內核的Linux發布上依然用得很好 -。用戶和應用程式作者可以將這個接口看成是穩定的。 +寫作本文檔的目的，是爲了解釋爲什麼Linux既沒有二進制內核接口，也沒有穩定 +的內核接口。這裏所說的內核接口，是指內核裏的接口，而不是內核和用戶空間 +的接口。內核到用戶空間的接口，是提供給應用程序使用的系統調用，系統調用 +在歷史上幾乎沒有過變化，將來也不會有變化。我有一些老應用程序是在0.9版本 +或者更早版本的內核上編譯的，在使用2.6版本內核的Linux發佈上依然用得很好 +。用戶和應用程序作者可以將這個接口看成是穩定的。 執行綱要 -------- 你也許以爲自己想要穩定的內核接口，但是你不清楚你要的實際上不是它。你需 -要的其實是穩定的驅動程序，而你只有將驅動程序放到公版內核的原始碼樹里， -才有可能達到這個目的。而且這樣做還有很多其它好處，正是因爲這些好處使得 -Linux能成爲強壯，穩定，成熟的作業系統，這也是你最開始選擇Linux的原因。 +要的其實是穩定的驅動程序，而你只有將驅動程序放到公版內核的源代碼樹裏， +纔有可能達到這個目的。而且這樣做還有很多其它好處，正是因爲這些好處使得 +Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選擇Linux的原因。 入門 ----- -只有那些寫驅動程序的「怪人」才會擔心內核接口的改變，對廣大用戶來說，既 +只有那些寫驅動程序的“怪人”纔會擔心內核接口的改變，對廣大用戶來說，既 看不到內核接口，也不需要去關心它。 首先，我不打算討論關於任何非GPL許可的內核驅動的法律問題，這些非GPL許可 -的驅動程序包括不公開原始碼，隱藏原始碼，二進位或者是用原始碼包裝，或者 -是其它任何形式的不能以GPL許可公開原始碼的驅動程序。如果有法律問題，請咨 -詢律師，我只是一個程式設計師，所以我只打算探討技術問題（不是小看法律問題， +的驅動程序包括不公開源代碼，隱藏源代碼，二進制或者是用源代碼包裝，或者 +是其它任何形式的不能以GPL許可公開源代碼的驅動程序。如果有法律問題，請諮 +詢律師，我只是一個程序員，所以我只打算探討技術問題（不是小看法律問題， 法律問題很實際，並且需要一直關注）。 -既然只談技術問題，我們就有了下面兩個主題：二進位內核接口和穩定的內核源 -代碼接口。這兩個問題是互相關聯的，讓我們先解決掉二進位接口的問題。 +既然只談技術問題，我們就有了下面兩個主題：二進制內核接口和穩定的內核源 +代碼接口。這兩個問題是互相關聯的，讓我們先解決掉二進制接口的問題。 -二進位內核接口 +二進制內核接口 -------------- -假如我們有一個穩定的內核原始碼接口，那麼自然而然的，我們就擁有了穩定的 -二進位接口，是這樣的嗎？錯。讓我們看看關於Linux內核的幾點事實： +假如我們有一個穩定的內核源代碼接口，那麼自然而然的，我們就擁有了穩定的 +二進制接口，是這樣的嗎？錯。讓我們看看關於Linux內核的幾點事實： - - 取決於所用的C編譯器的版本，不同的內核數據結構里的結構體的對齊方 + - 取決於所用的C編譯器的版本，不同的內核數據結構裏的結構體的對齊方 式會有差別，代碼中不同函數的表現形式也不一樣（函數是不是被inline 編譯取決於編譯器行爲）。不同的函數的表現形式並不重要，但是數據 結構內部的對齊方式很關鍵。 @@ -69,33 +69,33 @@ Linux能成爲強壯，穩定，成熟的作業系統，這也是你最開始選 項。 - Linux可以在很多的不同體系結構的處理器上運行。在某個體系結構上編 - 譯好的二進位驅動程序，不可能在另外一個體系結構上正確的運行。 + 譯好的二進制驅動程序，不可能在另外一個體繫結構上正確的運行。 對於一個特定的內核，滿足這些條件並不難，使用同一個C編譯器和同樣的內核配 -置選項來編譯驅動程序模塊就可以了。這對於給一個特定Linux發布的特定版本提 -供驅動程序，是完全可以滿足需求的。但是如果你要給不同發布的不同版本都發 -布一個驅動程序，就需要在每個發布上用不同的內核設置參數都編譯一次內核， -這簡直跟噩夢一樣。而且還要注意到，每個Linux發布還提供不同的Linux內核， -這些內核都針對不同的硬體類型進行了優化（有很多種不同的處理器，還有不同 -的內核設置選項）。所以每發布一次驅動程序，都需要提供很多不同版本的內核 +置選項來編譯驅動程序模塊就可以了。這對於給一個特定Linux發佈的特定版本提 +供驅動程序，是完全可以滿足需求的。但是如果你要給不同發佈的不同版本都發 +佈一個驅動程序，就需要在每個發佈上用不同的內核設置參數都編譯一次內核， +這簡直跟噩夢一樣。而且還要注意到，每個Linux發佈還提供不同的Linux內核， +這些內核都針對不同的硬件類型進行了優化（有很多種不同的處理器，還有不同 +的內核設置選項）。所以每發佈一次驅動程序，都需要提供很多不同版本的內核 模塊。 -相信我，如果你真的要採取這種發布方式，一定會慢慢瘋掉，我很久以前就有過 +相信我，如果你真的要採取這種發佈方式，一定會慢慢瘋掉，我很久以前就有過 深刻的教訓... -穩定的內核原始碼接口 +穩定的內核源代碼接口 -------------------- -如果有人不將他的內核驅動程序，放入公版內核的原始碼樹，而又想讓驅動程序 +如果有人不將他的內核驅動程序，放入公版內核的源代碼樹，而又想讓驅動程序 一直保持在最新的內核中可用，那麼這個話題將會變得沒完沒了。 內核開發是持續而且快節奏的，從來都不會慢下來。內核開發人員在當前接口中 找到bug，或者找到更好的實現方式。一旦發現這些，他們就很快會去修改當前的 -接口。修改接口意味著，函數名可能會改變，結構體可能被擴充或者刪減，函數 +接口。修改接口意味着，函數名可能會改變，結構體可能被擴充或者刪減，函數 的參數也可能發生改變。一旦接口被修改，內核中使用這些接口的地方需要同時 修正，這樣才能保證所有的東西繼續工作。 -舉一個例子，內核的USB驅動程序接口在USB子系統的整個生命周期中，至少經歷 +舉一個例子，內核的USB驅動程序接口在USB子系統的整個生命週期中，至少經歷 了三次重寫。這些重寫解決以下問題： - 把數據流從同步模式改成非同步模式，這個改動減少了一些驅動程序的 @@ -104,11 +104,11 @@ Linux能成爲強壯，穩定，成熟的作業系統，這也是你最開始選 - 修改了USB核心代碼中爲USB驅動分配數據包內存的方式，所有的驅動都 需要提供更多的參數給USB核心，以修正了很多已經被記錄在案的死鎖。 -這和一些封閉原始碼的作業系統形成鮮明的對比，在那些作業系統上，不得不額 +這和一些封閉源代碼的操作系統形成鮮明的對比，在那些操作系統上，不得不額 外的維護舊的USB接口。這導致了一個可能性，新的開發者依然會不小心使用舊的 -接口，以不恰當的方式編寫代碼，進而影響到作業系統的穩定性。 +接口，以不恰當的方式編寫代碼，進而影響到操作系統的穩定性。 在上面的例子中，所有的開發者都同意這些重要的改動，在這樣的情況下修改代 -價很低。如果Linux保持一個穩定的內核原始碼接口，那麼就得創建一個新的接口 +價很低。如果Linux保持一個穩定的內核源代碼接口，那麼就得創建一個新的接口 ；舊的，有問題的接口必須一直維護，給Linux USB開發者帶來額外的工作。既然 所有的Linux USB驅動的作者都是利用自己的時間工作，那麼要求他們去做毫無意 義的免費額外工作，是不可能的。 @@ -126,28 +126,28 @@ Linux能成爲強壯，穩定，成熟的作業系統，這也是你最開始選 要做什麼 -------- -如果你寫了一個Linux內核驅動，但是它還不在Linux原始碼樹里，作爲一個開發 -者，你應該怎麼做？爲每個發布的每個版本提供一個二進位驅動，那簡直是一個 +如果你寫了一個Linux內核驅動，但是它還不在Linux源代碼樹裏，作爲一個開發 +者，你應該怎麼做？爲每個發佈的每個版本提供一個二進制驅動，那簡直是一個 噩夢，要跟上永遠處於變化之中的內核接口，也是一件辛苦活。 -很簡單，讓你的驅動進入內核原始碼樹（要記得我們在談論的是以GPL許可發行 +很簡單，讓你的驅動進入內核源代碼樹（要記得我們在談論的是以GPL許可發行 的驅動，如果你的代碼不符合GPL，那麼祝你好運，你只能自己解決這個問題了， -你這個吸血鬼<把Andrew和Linus對吸血鬼的定義連結到這裡>）。當你的代碼加入 -公版內核原始碼樹之後，如果一個內核接口改變，你的驅動會直接被修改接口的 +你這個吸血鬼<把Andrew和Linus對吸血鬼的定義鏈接到這裏>）。當你的代碼加入 +公版內核源代碼樹之後，如果一個內核接口改變，你的驅動會直接被修改接口的 那個人修改。保證你的驅動永遠都可以編譯通過，並且一直工作，你幾乎不需要 做什麼事情。 -把驅動放到內核原始碼樹里會有很多的好處： +把驅動放到內核源代碼樹裏會有很多的好處： - 驅動的質量會提升，而維護成本（對原始作者來說）會下降。 - 其他人會給驅動添加新特性。 - 其他人會找到驅動中的bug並修復。 - 其他人會在驅動中找到性能優化的機會。 - 當外部的接口的改變需要修改驅動程序的時候，其他人會修改驅動程序 - - 不需要聯繫任何發行商，這個驅動會自動的隨著所有的Linux發布一起發 + - 不需要聯繫任何發行商，這個驅動會自動的隨着所有的Linux發佈一起發 布。 -和別的作業系統相比，Linux爲更多不同的設備提供現成的驅動，而且能在更多不 -同體系結構的處理器上支持這些設備。這個經過考驗的開發模式，必然是錯不了 +和別的操作系統相比，Linux爲更多不同的設備提供現成的驅動，而且能在更多不 +同體繫結構的處理器上支持這些設備。這個經過考驗的開發模式，必然是錯不了 的 :) 感謝 diff --git a/Documentation/translations/zh_TW/process/stable-kernel-rules.rst b/Documentation/translations/zh_TW/process/stable-kernel-rules.rst index 9bb0d9b4f3ac..4c66eb448eaa 100644 --- a/Documentation/translations/zh_TW/process/stable-kernel-rules.rst +++ b/Documentation/translations/zh_TW/process/stable-kernel-rules.rst @@ -17,10 +17,10 @@ - Kangkai Yin - 胡皓文 Hu Haowen -所有你想知道的事情 - 關於linux穩定版發布 +所有你想知道的事情 - 關於linux穩定版發佈 ======================================== -關於Linux 2.6穩定版發布，所有你想知道的事情。 +關於Linux 2.6穩定版發佈，所有你想知道的事情。 關於哪些類型的補丁可以被接收進入穩定版代碼樹，哪些不可以的規則： ---------------------------------------------------------------- @@ -28,39 +28,39 @@ - 必須是顯而易見的正確，並且經過測試的。 - 連同上下文，不能大於100行。 - 必須只修正一件事情。 - - 必須修正了一個給大家帶來麻煩的真正的bug（不是「這也許是一個問題...」 + - 必須修正了一個給大家帶來麻煩的真正的bug（不是“這也許是一個問題...” 那樣的東西）。 - 必須修正帶來如下後果的問題：編譯錯誤（對被標記爲CONFIG_BROKEN的例外）， - 內核崩潰，掛起，數據損壞，真正的安全問題，或者一些類似「哦，這不 - 好」的問題。簡短的說，就是一些致命的問題。 - - 沒有「理論上的競爭條件」，除非能給出競爭條件如何被利用的解釋。 - - 不能存在任何的「瑣碎的」修正（拼寫修正，去掉多餘空格之類的）。 + 內核崩潰，掛起，數據損壞，真正的安全問題，或者一些類似“哦，這不 + 好”的問題。簡短的說，就是一些致命的問題。 + - 沒有“理論上的競爭條件”，除非能給出競爭條件如何被利用的解釋。 + - 不能存在任何的“瑣碎的”修正（拼寫修正，去掉多餘空格之類的）。 - 必須被相關子系統的維護者接受。 - - 必須遵循Documentation/translations/zh_TW/process/submitting-patches.rst里的規則。 + - 必須遵循Documentation/translations/zh_CN/process/submitting-patches.rst裏的規則。 向穩定版代碼樹提交補丁的過程： ------------------------------ - 在確認了補丁符合以上的規則後，將補丁發送到stable@vger.kernel.org。 - - 如果補丁被接受到隊列里，發送者會收到一個ACK回復，如果沒有被接受，收 - 到的是NAK回復。回復需要幾天的時間，這取決於開發者的時間安排。 - - 被接受的補丁會被加到穩定版本隊列里，等待其他開發者的審查。 + - 如果補丁被接受到隊列裏，發送者會收到一個ACK回覆，如果沒有被接受，收 + 到的是NAK回覆。回覆需要幾天的時間，這取決於開發者的時間安排。 + - 被接受的補丁會被加到穩定版本隊列裏，等待其他開發者的審查。 - 安全方面的補丁不要發到這個列表，應該發送到security@kernel.org。 -審查周期： +審查週期： ---------- - - 當穩定版的維護者決定開始一個審查周期，補丁將被發送到審查委員會，以 + - 當穩定版的維護者決定開始一個審查週期，補丁將被髮送到審查委員會，以 及被補丁影響的領域的維護者（除非提交者就是該領域的維護者）並且抄送 到linux-kernel郵件列表。 - - 審查委員會有48小時的時間，用來決定給該補丁回復ACK還是NAK。 + - 審查委員會有48小時的時間，用來決定給該補丁回覆ACK還是NAK。 - 如果委員會中有成員拒絕這個補丁，或者linux-kernel列表上有人反對這個 補丁，並提出維護者和審查委員會之前沒有意識到的問題，補丁會從隊列中 丟棄。 - - 在審查周期結束的時候，那些得到ACK回應的補丁將會被加入到最新的穩定版 - 發布中，一個新的穩定版發布就此產生。 - - 安全性補丁將從內核安全小組那裡直接接收到穩定版代碼樹中，而不是通過 - 通常的審查周期。請聯繫內核安全小組以獲得關於這個過程的更多細節。 + - 在審查週期結束的時候，那些得到ACK回應的補丁將會被加入到最新的穩定版 + 發佈中，一個新的穩定版發佈就此產生。 + - 安全性補丁將從內核安全小組那裏直接接收到穩定版代碼樹中，而不是通過 + 通常的審查週期。請聯繫內核安全小組以獲得關於這個過程的更多細節。 審查委員會： ------------ diff --git a/Documentation/translations/zh_TW/process/submit-checklist.rst b/Documentation/translations/zh_TW/process/submit-checklist.rst index ff2f89cba83f..942962d1e2f4 100644 --- a/Documentation/translations/zh_TW/process/submit-checklist.rst +++ b/Documentation/translations/zh_TW/process/submit-checklist.rst @@ -2,108 +2,114 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/process/submit-checklist.rst ` -:Translator: Alex Shi - Hu Haowen +:Original: Documentation/process/submit-checklist.rst +:Translator: + - Alex Shi + - Wu XiangCheng + - Hu Haowen .. _tw_submitchecklist: -Linux內核補丁提交清單 -~~~~~~~~~~~~~~~~~~~~~ +Linux內核補丁提交檢查單 +~~~~~~~~~~~~~~~~~~~~~~~ 如果開發人員希望看到他們的內核補丁提交更快地被接受，那麼他們應該做一些基本 的事情。 -這些都是在 -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst ` +這些都是在 Documentation/translations/zh_CN/process/submitting-patches.rst 和其他有關提交Linux內核補丁的文檔中提供的。 -1) 如果使用工具，則包括定義/聲明該工具的文件。不要依賴於其他頭文件拉入您使用 +1) 如果使用工具，則包括定義/聲明該工具的文件。不要依賴其他頭文件來引入您使用 的頭文件。 2) 乾淨的編譯： - a) 使用適用或修改的 ``CONFIG`` 選項 ``=y``、``=m`` 和 ``=n`` 。沒有GCC - 警告/錯誤，沒有連結器警告/錯誤。 + a) 使用合適的 ``CONFIG`` 選項 ``=y``、``=m`` 和 ``=n`` 。沒有 ``gcc`` + 警告/錯誤，沒有鏈接器警告/錯誤。 - b) 通過allnoconfig、allmodconfig + b) 通過 ``allnoconfig`` 、 ``allmodconfig`` c) 使用 ``O=builddir`` 時可以成功編譯 -3) 通過使用本地交叉編譯工具或其他一些構建場在多個CPU體系結構上構建。 + d) 任何 Doucmentation/ 下的變更都能成功構建且不引入新警告/錯誤。 + 用 ``make htmldocs`` 或 ``make pdfdocs`` 檢驗構建情況並修復問題。 + +3) 通過使用本地交叉編譯工具或其他一些構建設施在多個CPU體系結構上構建。 4) PPC64是一種很好的交叉編譯檢查體系結構，因爲它傾向於對64位的數使用無符號 長整型。 -5) 如下所述 :ref:`Documentation/translations/zh_TW/process/coding-style.rst `. - 檢查您的補丁是否爲常規樣式。在提交（ ``scripts/check patch.pl`` ）之前， - 使用補丁樣式檢查器檢查是否有輕微的衝突。您應該能夠處理您的補丁中存在的所有 +5) 按 Documentation/translations/zh_CN/process/coding-style.rst 所述檢查您的 + 補丁是否爲常規樣式。在提交之前使用補丁樣式檢查器 ``scripts/checkpatch.pl`` + 檢查是否有輕微的衝突。您應該能夠處理您的補丁中存在的所有 違規行爲。 -6) 任何新的或修改過的 ``CONFIG`` 選項都不會弄髒配置菜單，並默認爲關閉，除非 - 它們符合 ``Documentation/kbuild/kconfig-language.rst`` 中記錄的異常條件, - 菜單屬性：默認值. +6) 任何新的或修改過的 ``CONFIG`` 選項都不應搞亂配置菜單，並默認爲關閉，除非 + 它們符合 ``Documentation/kbuild/kconfig-language.rst`` 菜單屬性：默認值中 + 記錄的例外條件。 7) 所有新的 ``kconfig`` 選項都有幫助文本。 -8) 已仔細審查了相關的 ``Kconfig`` 組合。這很難用測試來糾正——腦力在這裡是有 +8) 已仔細審查了相關的 ``Kconfig`` 組合。這很難用測試來糾正——腦力在這裏是有 回報的。 -9) 用 sparse 檢查乾淨。 +9) 通過 sparse 清查。 + （參見 Documentation/translations/zh_CN/dev-tools/sparse.rst ） 10) 使用 ``make checkstack`` 和 ``make namespacecheck`` 並修復他們發現的任何 問題。 .. note:: - ``checkstack`` 並沒有明確指出問題，但是任何一個在堆棧上使用超過512 + ``checkstack`` 並不會明確指出問題，但是任何一個在堆棧上使用超過512 字節的函數都可以進行更改。 -11) 包括 :ref:`kernel-doc ` 內核文檔以記錄全局內核API。（靜態函數 - 不需要，但也可以。）使用 ``make htmldocs`` 或 ``make pdfdocs`` 檢查 - :ref:`kernel-doc ` 並修復任何問題。 +11) 包括 :ref:`kernel-doc ` 內核文檔以記錄全局內核API。（靜態 + 函數不需要，但也可以。）使用 ``make htmldocs`` 或 ``make pdfdocs`` 檢查 + :ref:`kernel-doc ` 並修復任何問題。 -12) 通過以下選項同時啓用的測試 ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, +12) 通過以下選項同時啓用的測試： ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, - ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` - -13) 已經過構建和運行時測試，包括有或沒有 ``CONFIG_SMP``, ``CONFIG_PREEMPT``. + ``CONFIG_PROVE_RCU`` 和 ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` 。 -14) 如果補丁程序影響IO/磁碟等：使用或不使用 ``CONFIG_LBDAF`` 進行測試。 +13) 在 ``CONFIG_SMP``, ``CONFIG_PREEMPT`` 開啓和關閉的情況下都進行構建和運行 + 時測試。 -15) 所有代碼路徑都已在啓用所有lockdep功能的情況下運行。 +14) 所有代碼路徑都已在啓用所有死鎖檢測（lockdep）功能的情況下運行。 -16) 所有新的/proc條目都記錄在 ``Documentation/`` +15) 所有新的 ``/proc`` 條目都記錄在 ``Documentation/`` -17) 所有新的內核引導參數都記錄在 +16) 所有新的內核引導參數都記錄在 Documentation/admin-guide/kernel-parameters.rst 中。 -18) 所有新的模塊參數都記錄在 ``MODULE_PARM_DESC()`` +17) 所有新的模塊參數都記錄在 ``MODULE_PARM_DESC()`` -19) 所有新的用戶空間接口都記錄在 ``Documentation/ABI/`` 中。有關詳細信息， +18) 所有新的用戶空間接口都記錄在 ``Documentation/ABI/`` 中。有關詳細信息， 請參閱 ``Documentation/ABI/README`` 。更改用戶空間接口的補丁應該抄送 linux-api@vger.kernel.org。 -20) 已通過至少注入slab和page分配失敗進行檢查。請參閱 ``Documentation/fault-injection/`` +19) 已通過至少注入slab和page分配失敗進行檢查。請參閱 ``Documentation/fault-injection/`` 。 如果新代碼是實質性的，那麼添加子系統特定的故障注入可能是合適的。 -21) 新添加的代碼已經用 ``gcc -W`` 編譯（使用 ``make EXTRA-CFLAGS=-W`` ）。這 - 將產生大量噪聲，但對於查找諸如「警告：有符號和無符號之間的比較」之類的錯誤 +20) 新添加的代碼已經用 ``gcc -W`` 編譯（使用 ``make EXTRA-CFLAGS=-W`` ）。這 + 將產生大量噪聲，但對於查找諸如“警告：有符號和無符號之間的比較”之類的錯誤 很有用。 -22) 在它被合併到-mm補丁集中之後進行測試，以確保它仍然與所有其他排隊的補丁以 +21) 在它被合併到-mm補丁集中之後進行測試，以確保它仍然與所有其他排隊的補丁以 及VM、VFS和其他子系統中的各種更改一起工作。 -23) 所有內存屏障例如 ``barrier()``, ``rmb()``, ``wmb()`` 都需要原始碼中的注 +22) 所有內存屏障（例如 ``barrier()``, ``rmb()``, ``wmb()`` ）都需要源代碼注 釋來解釋它們正在執行的操作及其原因的邏輯。 -24) 如果補丁添加了任何ioctl，那麼也要更新 ``Documentation/userspace-api/ioctl/ioctl-number.rst`` +23) 如果補丁添加了任何ioctl，那麼也要更新 + ``Documentation/userspace-api/ioctl/ioctl-number.rst`` 。 -25) 如果修改後的原始碼依賴或使用與以下 ``Kconfig`` 符號相關的任何內核API或 +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``). + ``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`` ）。 diff --git a/Documentation/translations/zh_TW/process/submitting-patches.rst b/Documentation/translations/zh_TW/process/submitting-patches.rst index 3f77ef5d48a0..ac1c3bb78adb 100644 --- a/Documentation/translations/zh_TW/process/submitting-patches.rst +++ b/Documentation/translations/zh_TW/process/submitting-patches.rst @@ -1,229 +1,199 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. _tw_submittingpatches: +.. SPDX-License-Identifier: GPL-2.0-or-later .. include:: ../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/process/submitting-patches.rst ` +.. _tw_submittingpatches: + +:Original: Documentation/process/submitting-patches.rst -譯者:: +:譯者: + - 鍾宇 TripleX Chung + - 時奎亮 Alex Shi + - 吳想成 Wu XiangCheng - 中文版維護者： 鍾宇 TripleX Chung - 中文版翻譯者： 鍾宇 TripleX Chung - 時奎亮 Alex Shi - 中文版校譯者： 李陽 Li Yang - 王聰 Wang Cong - 胡皓文 Hu Haowen +:校譯: + - 李陽 Li Yang + - 王聰 Wang Cong + - 胡皓文 Hu Haowen -如何讓你的改動進入內核 -====================== +提交補丁：如何讓你的改動進入內核 +================================ -對於想要將改動提交到 Linux 內核的個人或者公司來說，如果不熟悉「規矩」， -提交的流程會讓人畏懼。本文檔收集了一系列建議，這些建議可以大大的提高你 +對於想要將改動提交到 Linux 內核的個人或者公司來說，如果不熟悉“規矩”， +提交的流程會讓人畏懼。本文檔包含了一系列建議，可以大大提高你 的改動被接受的機會. -以下文檔含有大量簡潔的建議， 具體請見： -:ref:`Documentation/process ` -同樣，:ref:`Documentation/translations/zh_TW/process/submit-checklist.rst ` -給出在提交代碼前需要檢查的項目的列表。 +本文檔以較爲簡潔的行文給出了大量建議。關於內核開發流程如何進行的詳細信息， +參見： Documentation/translations/zh_CN/process/development-process.rst 。 +Documentation/translations/zh_CN/process/submit-checklist.rst 給出了一系列 +提交補丁之前要檢查的事項。設備樹相關的補丁，請參閱 +Documentation/devicetree/bindings/submitting-patches.rst 。 -其中許多步驟描述了Git版本控制系統的默認行爲；如果您使用Git來準備補丁， -您將發現它爲您完成的大部分機械工作，儘管您仍然需要準備和記錄一組合理的 -補丁。一般來說，使用git將使您作爲內核開發人員的生活更輕鬆。 +本文檔假設您正在使用 ``git`` 準備你的補丁。如果您不熟悉 ``git`` ，最好學習 +如何使用它，這將使您作爲內核開發人員的生活變得更加輕鬆。 +部分子系統和維護人員的樹有一些關於其工作流程和要求的額外信息，請參閱 +Documentation/process/maintainer-handbooks.rst 。 -0) 獲取當前源碼樹 ------------------ +獲取當前源碼樹 +-------------- -如果您沒有一個可以使用當前內核原始碼的存儲庫，請使用git獲取一個。您將要 -從主線存儲庫開始，它可以通過以下方式獲取:: +如果您手頭沒有當前內核源代碼的存儲庫，請使用 ``git`` 獲取一份。您需要先獲取 +主線存儲庫，它可以通過以下命令拉取:: - git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git -但是，請注意，您可能不希望直接針對主線樹進行開發。大多數子系統維護人員運 +但是，請注意，您可能不想直接針對主線樹進行開發。大多數子系統維護人員運 行自己的樹，並希望看到針對這些樹準備的補丁。請參見MAINTAINERS文件中子系 -統的 **T:** 項以查找該樹，或者簡單地詢問維護者該樹是否未在其中列出。 - -仍然可以通過tarballs下載內核版本（如下一節所述），但這是進行內核開發的 -一種困難的方式。 - -1) "diff -up" -------------- - -使用 "diff -up" 或者 "diff -uprN" 來創建補丁。 - -所有內核的改動，都是以補丁的形式呈現的，補丁由 diff(1) 生成。創建補丁的 -時候，要確認它是以 "unified diff" 格式創建的，這種格式由 diff(1) 的 '-u' -參數生成。而且，請使用 '-p' 參數，那樣會顯示每個改動所在的C函數，使得 -產生的補丁容易讀得多。補丁應該基於內核原始碼樹的根目錄，而不是裡邊的任 -何子目錄。 - -爲一個單獨的文件創建補丁，一般來說這樣做就夠了:: - - SRCTREE=linux - MYFILE=drivers/net/mydriver.c - - cd $SRCTREE - cp $MYFILE $MYFILE.orig - vi $MYFILE # make your change - cd .. - diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch - -爲多個文件創建補丁，你可以解開一個沒有修改過的內核原始碼樹，然後和你自 -己的代碼樹之間做 diff 。例如:: - - MYSRC=/devel/linux - - tar xvfz linux-3.19.tar.gz - mv linux-3.19 linux-3.19-vanilla - diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ - linux-3.19-vanilla $MYSRC > /tmp/patch - -"dontdiff" 是內核在編譯的時候產生的文件的列表，列表中的文件在 diff(1) -產生的補丁里會被跳過。 - -確定你的補丁里沒有包含任何不屬於這次補丁提交的額外文件。記得在用diff(1) -生成補丁之後，審閱一次補丁，以確保準確。 +統的 **T:** 項以查找該樹，或者直接詢問維護者該樹是否未在其中列出。 -如果你的改動很散亂，你應該研究一下如何將補丁分割成獨立的部分，將改動分 -割成一系列合乎邏輯的步驟。這樣更容易讓其他內核開發者審核，如果你想你的 -補丁被接受，這是很重要的。請參閱： -:ref:`tw_split_changes` +.. _zh_describe_changes: -如果你用 ``git`` , ``git rebase -i`` 可以幫助你這一點。如果你不用 ``git``, -``quilt`` 另外一個流行的選擇。 - -.. _tw_describe_changes: - -2) 描述你的改動 ---------------- +描述你的改動 +------------ 描述你的問題。無論您的補丁是一行錯誤修復還是5000行新功能，都必須有一個潛在 -的問題激勵您完成這項工作。讓審稿人相信有一個問題值得解決，讓他們讀完第一段 -是有意義的。 +的問題激勵您完成這項工作。說服審閱者相信有一個問題值得解決，讓他們讀完第一段 +後就能明白這一點。 描述用戶可見的影響。直接崩潰和鎖定是相當有說服力的，但並不是所有的錯誤都那麼 -明目張胆。即使在代碼審查期間發現了這個問題，也要描述一下您認爲它可能對用戶產 +明目張膽。即使在代碼審閱期間發現了這個問題，也要描述一下您認爲它可能對用戶產 生的影響。請記住，大多數Linux安裝運行的內核來自二級穩定樹或特定於供應商/產品 的樹，只從上游精選特定的補丁，因此請包含任何可以幫助您將更改定位到下游的內容： -觸發的場景、DMESG的摘錄、崩潰描述、性能回歸、延遲尖峯、鎖定等。 +觸發的場景、DMESG的摘錄、崩潰描述、性能迴歸、延遲尖峯、鎖定等。 -量化優化和權衡。如果您聲稱在性能、內存消耗、堆棧占用空間或二進位大小方面有所 -改進，請包括支持它們的數字。但也要描述不明顯的成本。優化通常不是免費的，而是 -在CPU、內存和可讀性之間進行權衡；或者，探索性的工作，在不同的工作負載之間進 +質量優化和權衡。如果您聲稱在性能、內存消耗、堆棧佔用空間或二進制大小方面有所 +改進，請包括支持它們的數據。但也要描述不明顯的成本。優化通常不是零成本的，而是 +在CPU、內存和可讀性之間進行權衡；或者，做探索性的工作，在不同的工作負載之間進 行權衡。請描述優化的預期缺點，以便審閱者可以權衡成本和收益。 -一旦問題建立起來，就要詳細地描述一下您實際在做什麼。對於審閱者來說，用簡單的 -英語描述代碼的變化是很重要的，以驗證代碼的行爲是否符合您的意願。 +提出問題之後，就要詳細地描述一下您實際在做的技術細節。對於審閱者來說，用簡練的 +英語描述代碼的變化是很重要的，以驗證代碼的行爲是否符合您的意圖。 -如果您將補丁描述寫在一個表單中，這個表單可以很容易地作爲「提交日誌」放入Linux -的原始碼管理系統git中，那麼維護人員將非常感謝您。見 :ref:`tw_explicit_in_reply_to`. +如果您將補丁描述寫成“標準格式”，可以很容易地作爲“提交日誌”放入Linux的源代 +碼管理系統 ``git`` 中，那麼維護人員將非常感謝您。 +參見 :ref:`zh_the_canonical_patch_format` 。 每個補丁只解決一個問題。如果你的描述開始變長，這就表明你可能需要拆分你的補丁。 -請見 :ref:`tw_split_changes` +請見 :ref:`zh_split_changes` 。 -提交或重新提交修補程序或修補程序系列時，請包括完整的修補程序說明和理由。不要 +提交或重新提交補丁或補丁系列時，請包括完整的補丁說明和理由。不要 只說這是補丁（系列）的第幾版。不要期望子系統維護人員引用更早的補丁版本或引用 URL來查找補丁描述並將其放入補丁中。也就是說，補丁（系列）及其描述應該是獨立的。 -這對維護人員和審查人員都有好處。一些評審者可能甚至沒有收到補丁的早期版本。 +這對維護人員和審閱者都有好處。一些審閱者可能甚至沒有收到補丁的早期版本。 -描述你在命令語氣中的變化，例如「make xyzzy do frotz」而不是「[這個補丁]make -xyzzy do frotz」或「[我]changed xyzzy to do frotz」，就好像你在命令代碼庫改變 +用祈使句描述你的變更，例如“make xyzzy do frotz”而不是“[This patch]make +xyzzy do frotz”或“[I]changed xyzzy to do frotz”，就好像你在命令代碼庫改變 它的行爲一樣。 -如果修補程序修復了一個記錄的bug條目，請按編號和URL引用該bug條目。如果補丁來 -自郵件列表討論，請給出郵件列表存檔的URL；使用帶有 ``Message-ID`` 的 -https://lore.kernel.org/ 重定向，以確保連結不會過時。 - -但是，在沒有外部資源的情況下，儘量讓你的解釋可理解。除了提供郵件列表存檔或 -bug的URL之外，還要總結需要提交補丁的相關討論要點。 - -如果您想要引用一個特定的提交，不要只引用提交的 SHA-1 ID。還請包括提交的一行 -摘要，以便於審閱者了解它是關於什麼的。例如:: +如果您想要引用一個特定的提交，不要只引用提交的SHA-1 ID。還請包括提交的一行 +摘要，以便於審閱者瞭解它是關於什麼的。例如:: Commit e21d2170f36602ae2708 ("video: remove unnecessary platform_set_drvdata()") removed the unnecessary platform_set_drvdata(), but left the variable "dev" unused, delete it. -您還應該確保至少使用前12位 SHA-1 ID. 內核存儲庫包含*許多*對象，使與較短的ID +您還應該確保至少使用前12位SHA-1 ID。內核存儲庫包含 *許多* 對象，使較短的ID 發生衝突的可能性很大。記住，即使現在不會與您的六個字符ID發生衝突，這種情況 -可能五年後改變。 +也可能在五年後改變。 + +如果該變更的相關討論或背景信息可以在網上查閱，請加上“Link:”標籤指向它。例如 +你的補丁修復了一個缺陷，需要添加一個帶有URL的標籤指向郵件列表存檔或缺陷跟蹤器 +的相關報告；如果該補丁是由一些早先郵件列表討論或網絡上的記錄引起的，請指向它。 + +當鏈接到郵件列表存檔時，請首選lore.kernel.org郵件存檔服務。用郵件中的 +``Message-ID`` 頭（去掉尖括號）可以創建鏈接URL。例如:: + + Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + +請檢查該鏈接以確保可用且指向正確的郵件。 -如果修補程序修復了特定提交中的錯誤，例如，使用 ``git bisct`` ，請使用帶有前 -12個字符SHA-1 ID 的"Fixes:"標記和單行摘要。爲了簡化不要將標記拆分爲多個， -行、標記不受分析腳本「75列換行」規則的限制。例如:: +不過，在沒有外部資源的情況下，也要儘量讓你的解釋可理解。除了提供郵件列表存檔或 +缺陷的URL之外，還要需要總結該補丁的相關討論要點。 - Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") +如果補丁修復了特定提交中的錯誤，例如使用 ``git bisct`` 發現了一個問題，請使用 +帶有前12個字符SHA-1 ID的“Fixes:”標籤和單行摘要。爲了簡化解析腳本，不要將該 +標籤拆分爲多行，標籤不受“75列換行”規則的限制。例如:: -下列 ``git config`` 設置可以添加讓 ``git log``, ``git show`` 漂亮的顯示格式:: + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + +下列 ``git config`` 設置可以讓 ``git log``, ``git show`` 增加上述風格的顯示格式:: [core] abbrev = 12 [pretty] fixes = Fixes: %h (\"%s\") -.. _tw_split_changes: +使用示例:: + + $ git log -1 --pretty=fixes 54a4f0239f2e + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") -3) 拆分你的改動 ---------------- +.. _zh_split_changes: -將每個邏輯更改分隔成一個單獨的補丁。 +拆分你的改動 +------------ -例如，如果你的改動里同時有bug修正和性能優化，那麼把這些改動拆分到兩個或 -者更多的補丁文件中。如果你的改動包含對API的修改，並且修改了驅動程序來適 -應這些新的API，那麼把這些修改分成兩個補丁。 +將每個 **邏輯更改** 拆分成一個單獨的補丁。 + +例如，如果你的改動裏同時有bug修正和性能優化，那麼把這些改動拆分到兩個或 +者更多的補丁文件中。如果你的改動包含對API的修改，並且增加了一個使用該新API +的驅動，那麼把這些修改分成兩個補丁。 另一方面，如果你將一個單獨的改動做成多個補丁文件，那麼將它們合併成一個 -單獨的補丁文件。這樣一個邏輯上單獨的改動只被包含在一個補丁文件里。 +單獨的補丁文件。這樣一個邏輯上單獨的改動只被包含在一個補丁文件裏。 + +需要記住的一點是，每個補丁的更改都應易於理解，以便審閱者驗證。每個補丁都應該 +對其價值進行闡述。 -如果有一個補丁依賴另外一個補丁來完成它的改動，那沒問題。簡單的在你的補 -丁描述里指出「這個補丁依賴某補丁」就好了。 +如果有一個補丁依賴另外一個補丁來完成它的改動，那沒問題。直接在你的補 +丁描述裏指出 **“這個補丁依賴某補丁”** 就好了。 -在將您的更改劃分爲一系列補丁時，要特別注意確保內核在系列中的每個補丁之後 -都能正常構建和運行。使用 ``git bisect`` 來追蹤問題的開發者可能會在任何時 -候分割你的補丁系列；如果你在中間引入錯誤，他們不會感謝你。 +在將您的更改劃分爲一系列補丁時，要特別注意確保內核在應用系列中的每個補丁之後 +都能正常構建和運行。使用 ``git bisect`` 來追蹤問題的開發者可能會在任何地方分 +割你的補丁系列；如果你在中間引入錯誤，他們不會感謝你。 -如果你不能將補丁濃縮成更少的文件，那麼每次大約發送出15個，然後等待審查 +如果你不能將補丁系列濃縮得更小，那麼每次大約發送出15個補丁，然後等待審閱 和集成。 -4) 檢查你的更改風格 -------------------- +檢查你的更改風格 +---------------- -檢查您的補丁是否存在基本樣式衝突，詳細信息可在 -:ref:`Documentation/translations/zh_TW/process/coding-style.rst ` -中找到。如果不這樣做，只會浪費審稿人的時間，並且會導致你的補丁被拒絕，甚至 +檢查您的補丁是否違反了基本樣式規定，詳細信息參見 +Documentation/translations/zh_CN/process/coding-style.rst +中找到。如果不這樣做，只會浪費審閱者的時間，並且會導致你的補丁被拒絕，甚至 可能沒有被閱讀。 一個重要的例外是在將代碼從一個文件移動到另一個文件時——在這種情況下，您不應 該在移動代碼的同一個補丁中修改移動的代碼。這清楚地描述了移動代碼和您的更改 -的行爲。這大大有助於審查實際差異，並允許工具更好地跟蹤代碼本身的歷史。 +的行爲。這大大有助於審閱實際差異，並允許工具更好地跟蹤代碼本身的歷史。 在提交之前，使用補丁樣式檢查程序檢查補丁（scripts/check patch.pl）。不過， 請注意，樣式檢查程序應該被視爲一個指南，而不是作爲人類判斷的替代品。如果您 -的代碼看起來更好，但有違規行爲，那麼最好不要使用它。 +的代碼看起來更好，但有違規行爲，那麼最好別管它。 檢查者報告三個級別： - ERROR：很可能出錯的事情 - - WARNING：需要仔細審查的事項 + - WARNING：需要仔細審閱的事項 - CHECK：需要思考的事情 您應該能夠判斷您的補丁中存在的所有違規行爲。 -5) 選擇補丁收件人 ------------------ +選擇補丁收件人 +-------------- -您應該總是在任何補丁上複製相應的子系統維護人員，以獲得他們維護的代碼；查看 -維護人員文件和原始碼修訂歷史記錄，以了解這些維護人員是誰。腳本 -scripts/get_Maintainer.pl在這個步驟中非常有用。如果您找不到正在工作的子系統 +您應該總是知會任何補丁相應代碼的子系統維護人員；查看 +維護人員文件和源代碼修訂歷史記錄，以瞭解這些維護人員是誰。腳本 +scripts/get_maintainer.pl在這個步驟中非常有用。如果您找不到正在工作的子系統 的維護人員，那麼Andrew Morton（akpm@linux-foundation.org）將充當最後的維護 人員。 -您通常還應該選擇至少一個郵件列表來接收補丁集的。linux-kernel@vger.kernel.org -作爲最後一個解決辦法的列表，但是這個列表上的體積已經引起了許多開發人員的拒絕。 -在MAINTAINERS文件中查找子系統特定的列表；您的補丁可能會在那裡得到更多的關注。 +您通常還應該選擇至少一個郵件列表來接收補丁集的副本。linux-kernel@vger.kernel.org +是所有補丁的默認列表，但是這個列表的流量已經導致了許多開發人員不再看它。 +在MAINTAINERS文件中查找子系統特定的列表；您的補丁可能會在那裏得到更多的關注。 不過，請不要發送垃圾郵件到無關的列表。 許多與內核相關的列表託管在vger.kernel.org上；您可以在 @@ -232,188 +202,170 @@ http://vger.kernel.org/vger-lists.html 上找到它們的列表。不過，也 不要一次發送超過15個補丁到vger郵件列表！！！！ -Linus Torvalds 是決定改動能否進入 Linux 內核的最終裁決者。他的 e-mail -地址是 。他收到的 e-mail 很多，所以一般 -的說，最好別給他發 e-mail。 - -如果您有修復可利用安全漏洞的補丁，請將該補丁發送到 security@kernel.org。對於 -嚴重的bug，可以考慮短期暫停以允許分銷商向用戶發布補丁；在這種情況下，顯然不應 -將補丁發送到任何公共列表。 +Linus Torvalds是決定改動能否進入 Linux 內核的最終裁決者。他的郵件地址是 +torvalds@linux-foundation.org 。他收到的郵件很多，所以一般來說最好 **別** +給他發郵件。 -修復已發布內核中嚴重錯誤的補丁程序應該指向穩定版維護人員，方法是放這樣的一行:: +如果您有修復可利用安全漏洞的補丁，請將該補丁發送到 security@kernel.org 。對於 +嚴重的bug，可以考慮短期禁令以允許分銷商（有時間）向用戶發佈補丁；在這種情況下， +顯然不應將補丁發送到任何公共列表。 +參見 Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。 - Cc: stable@vger.kernel.org +修復已發佈內核中嚴重錯誤的補丁程序應該抄送給穩定版維護人員，方法是把以下列行 +放進補丁的籤準區（注意，不是電子郵件收件人）:: -進入補丁的簽准區（注意，不是電子郵件收件人）。除了這個文件之外，您還應該閱讀 -:ref:`Documentation/process/stable-kernel-rules.rst ` + Cc: stable@vger.kernel.org -但是，請注意，一些子系統維護人員希望得出他們自己的結論，即哪些補丁應該被放到 -穩定的樹上。尤其是網絡維護人員，不希望看到單個開發人員在補丁中添加像上面這樣 -的行。 +除了本文件之外，您還應該閱讀 +Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。 -如果更改影響到用戶和內核接口，請向手冊頁維護人員（如維護人員文件中所列）發送 +如果更改影響到用戶側內核接口，請向手冊頁維護人員（如維護人員文件中所列）發送 手冊頁補丁，或至少發送更改通知，以便一些信息進入手冊頁。還應將用戶空間API -更改複製到 linux-api@vger.kernel.org。 +更改抄送到 linux-api@vger.kernel.org 。 -6) 沒有 MIME 編碼，沒有連結，沒有壓縮，沒有附件，只有純文本 ------------------------------------------------------------ + +不要MIME編碼，不要鏈接，不要壓縮，不要附件，只要純文本 +------------------------------------------------------ Linus 和其他的內核開發者需要閱讀和評論你提交的改動。對於內核開發者來說 -，可以「引用」你的改動很重要，使用一般的 e-mail 工具，他們就可以在你的 +，可以“引用”你的改動很重要，使用一般的郵件工具，他們就可以在你的 代碼的任何位置添加評論。 -因爲這個原因，所有的提交的補丁都是 e-mail 中「內嵌」的。 +因爲這個原因，所有的提交的補丁都是郵件中“內嵌”的。最簡單（和推薦）的方法就 +是使用 ``git send-email`` 。https://git-send-email.io 有 ``git send-email`` +的交互式教程。 + +如果你選擇不用 ``git send-email`` ： .. warning:: - 如果你使用剪切-粘貼你的補丁，小心你的編輯器的自動換行功能破壞你的補丁 -不要將補丁作爲 MIME 編碼的附件，不管是否壓縮。很多流行的 e-mail 軟體不 -是任何時候都將 MIME 編碼的附件當作純文本發送的，這會使得別人無法在你的 -代碼中加評論。另外，MIME 編碼的附件會讓 Linus 多花一點時間來處理，這就 -降低了你的改動被接受的可能性。 + 如果你使用剪切-粘貼你的補丁，小心你的編輯器的自動換行功能破壞你的補丁 -例外：如果你的郵遞員弄壞了補丁，那麼有人可能會要求你使用mime重新發送補丁 +不要將補丁作爲MIME編碼的附件，不管是否壓縮。很多流行的郵件軟件不 +是任何時候都將MIME編碼的附件當作純文本發送的，這會使得別人無法在你的 +代碼中加評論。另外，MIME編碼的附件會讓Linus多花一點時間來處理，這就 +降低了你的改動被接受的可能性。 -請參閱 :ref:`Documentation/translations/zh_TW/process/email-clients.rst ` -以獲取有關配置電子郵件客戶端以使其不受影響地發送修補程序的提示。 +例外：如果你的郵路損壞了補丁，那麼有人可能會要求你使用MIME重新發送補丁。 -7) e-mail 的大小 ----------------- +請參閱 Documentation/translations/zh_CN/process/email-clients.rst +以獲取有關配置電子郵件客戶端以使其不受影響地發送補丁的提示。 -大的改動對郵件列表不合適，對某些維護者也不合適。如果你的補丁，在不壓縮 -的情況下，超過了300kB，那麼你最好將補丁放在一個能通過 internet 訪問的服 -務器上，然後用指向你的補丁的 URL 替代。但是請注意，如果您的補丁超過了 -300kb，那麼它幾乎肯定需要被破壞。 +回覆審閱意見 +------------ -8）回複評審意見 ---------------- +你的補丁幾乎肯定會得到審閱者對補丁改進方法的評論（以回覆郵件的形式）。您必須 +對這些評論作出回應；讓補丁被忽略的一個好辦法就是忽略審閱者的意見。直接回復郵 +件來回應意見即可。不會導致代碼更改的意見或問題幾乎肯定會帶來註釋或變更日誌的 +改變，以便下一個審閱者更好地瞭解正在發生的事情。 -你的補丁幾乎肯定會得到評審者對補丁改進方法的評論。您必須對這些評論作出 -回應；讓補丁被忽略的一個好辦法就是忽略審閱者的意見。不會導致代碼更改的 -意見或問題幾乎肯定會帶來注釋或變更日誌的改變，以便下一個評審者更好地了解 -正在發生的事情。 +一定要告訴審閱者你在做什麼改變，並感謝他們的時間。代碼審閱是一個累人且耗時的 +過程，審閱者有時會變得暴躁。即使在這種情況下，也要禮貌地回應並解決他們指出的 +問題。當發送下一版時，在封面郵件或獨立補丁里加上 ``patch changelog`` 說明與 +前一版本的不同之處（參見 :ref:`zh_the_canonical_patch_format` ）。 -一定要告訴審稿人你在做什麼改變，並感謝他們的時間。代碼審查是一個累人且 -耗時的過程，審查人員有時會變得暴躁。即使在這種情況下，也要禮貌地回應並 -解決他們指出的問題。 +.. _zh_resend_reminders: -9）不要洩氣或不耐煩 -------------------- +不要泄氣或不耐煩 +---------------- -提交更改後，請耐心等待。審閱者是忙碌的人，可能無法立即訪問您的修補程序。 +提交更改後，請耐心等待。審閱者是大忙人，可能無法立即審閱您的補丁。 -曾幾何時，補丁曾在沒有評論的情況下消失在空白中，但開發過程比現在更加順利。 -您應該在一周左右的時間內收到評論；如果沒有收到評論，請確保您已將補丁發送 -到正確的位置。在重新提交或聯繫審閱者之前至少等待一周-在諸如合併窗口之類的 +曾幾何時，補丁曾在沒收到評論的情況下消失在虛空中，但現在開發過程應該更加順利了。 +您應該在一週左右的時間內收到評論；如果沒有收到評論，請確保您已將補丁發送 +到正確的位置。在重新提交或聯繫審閱者之前至少等待一週——在諸如合併窗口之類的 繁忙時間可能更長。 -10）主題中包含 PATCH --------------------- +在等了幾個星期後，用帶RESEND的主題重發補丁也是可以的:: -由於到linus和linux內核的電子郵件流量很高，通常會在主題行前面加上[PATCH] -前綴. 這使Linus和其他內核開發人員更容易將補丁與其他電子郵件討論區分開。 + [PATCH Vx RESEND] sub/sys: Condensed patch summary -11）簽署你的作品-開發者原始認證 -------------------------------- - -爲了加強對誰做了何事的追蹤，尤其是對那些透過好幾層的維護者的補丁，我們 -建議在發送出去的補丁上加一個 「sign-off」 的過程。 - -"sign-off" 是在補丁的注釋的最後的簡單的一行文字，認證你編寫了它或者其他 -人有權力將它作爲開放原始碼的補丁傳遞。規則很簡單：如果你能認證如下信息: - -開發者來源證書 1.1 -^^^^^^^^^^^^^^^^^^ +當你發佈補丁（系列）修改版的時候，不要加上“RESEND”——“RESEND”只適用於重 +新提交之前未經修改的補丁（系列）。 -對於本項目的貢獻，我認證如下信息： +主題中包含 PATCH +---------------- - （a）這些貢獻是完全或者部分的由我創建，我有權利以文件中指出 - 的開放原始碼許可證提交它；或者 - （b）這些貢獻基於以前的工作，據我所知，這些以前的工作受恰當的開放 - 原始碼許可證保護，而且，根據許可證，我有權提交修改後的貢獻， - 無論是完全還是部分由我創造，這些貢獻都使用同一個開放原始碼許可證 - （除非我被允許用其它的許可證），正如文件中指出的；或者 - （c）這些貢獻由認證（a），（b）或者（c）的人直接提供給我，而 - 且我沒有修改它。 - （d）我理解並同意這個項目和貢獻是公開的，貢獻的記錄（包括我 - 一起提交的個人記錄，包括 sign-off ）被永久維護並且可以和這個項目 - 或者開放原始碼的許可證同步地再發行。 +由於到Linus和linux-kernel的電子郵件流量很高，通常會在主題行前面加上[PATCH] +前綴。這使Linus和其他內核開發人員更容易將補丁與其他電子郵件討論區分開。 -那麼加入這樣一行:: +``git send-email`` 會自動爲你加上。 - Signed-off-by: Random J Developer +簽署你的作品——開發者來源認證 +------------------------------ -使用你的真名（抱歉，不能使用假名或者匿名。） +爲了加強對誰做了何事的追蹤，尤其是對那些透過好幾層維護者才最終到達的補丁，我 +們在通過郵件發送的補丁上引入了“簽署（sign-off）”流程。 -有人在最後加上標籤。現在這些東西會被忽略，但是你可以這樣做，來標記公司 -內部的過程，或者只是指出關於 sign-off 的一些特殊細節。 +“簽署”是在補丁註釋最後的一行簡單文字，認證你編寫了它或者其他 +人有權力將它作爲開放源代碼的補丁傳遞。規則很簡單：如果你能認證如下信息: -如果您是子系統或分支維護人員，有時需要稍微修改收到的補丁，以便合併它們， -因爲樹和提交者中的代碼不完全相同。如果你嚴格遵守規則（c），你應該要求提交者 -重新發布，但這完全是在浪費時間和精力。規則（b）允許您調整代碼，但是更改一個 -提交者的代碼並讓他認可您的錯誤是非常不禮貌的。要解決此問題，建議在最後一個 -由簽名行和您的行之間添加一行，指示更改的性質。雖然這並不是強制性的，但似乎 -在描述前加上您的郵件和/或姓名（全部用方括號括起來），這足以讓人注意到您對最 -後一分鐘的更改負有責任。例如:: +開發者來源認證 1.1 +^^^^^^^^^^^^^^^^^^ - Signed-off-by: Random J Developer - [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] - Signed-off-by: Lucky K Maintainer +對於本項目的貢獻，我認證如下信息： -如果您維護一個穩定的分支機構，同時希望對作者進行致謝、跟蹤更改、合併修復並 -保護提交者不受投訴，那麼這種做法尤其有用。請注意，在任何情況下都不能更改作者 -的ID（From 頭），因爲它是出現在更改日誌中的標識。 + (a) 這些貢獻是完全或者部分的由我創建，我有權利以文件中指出 + 的開放源代碼許可證提交它；或者 -對回合（back-porters）的特別說明：在提交消息的頂部（主題行之後）插入一個補丁 -的起源指示似乎是一種常見且有用的實踐，以便於跟蹤。例如，下面是我們在3.x穩定 -版本中看到的內容:: + (b) 這些貢獻基於以前的工作，據我所知，這些以前的工作受恰當的開放 + 源代碼許可證保護，而且，根據文件中指出的許可證，我有權提交修改後的貢獻， + 無論是完全還是部分由我創造，這些貢獻都使用同一個開放源代碼許可證 + （除非我被允許用其它的許可證）；或者 - Date: Tue Oct 7 07:26:38 2014 -0400 + (c) 這些貢獻由認證（a），（b）或者（c）的人直接提供給我，而 + 且我沒有修改它。 - libata: Un-break ATA blacklist + (d) 我理解並同意這個項目和貢獻是公開的，貢獻的記錄（包括我 + 一起提交的個人記錄，包括sign-off）被永久維護並且可以和這個項目 + 或者開放源代碼的許可證同步地再發行。 - commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. +那麼加入這樣一行:: -還有， 這裡是一個舊版內核中的一個回合補丁:: + Signed-off-by: Random J Developer - Date: Tue May 13 22:12:27 2008 +0200 +使用你的真名（抱歉，不能使用假名或者匿名。）如果使用 ``git commit -s`` 的話 +將會自動完成。撤銷也應當包含“Signed-off-by”， ``git revert -s`` 會幫你搞定。 - wireless, airo: waitbusy() won't delay +有些人會在最後加上額外的標籤。現在這些東西會被忽略，但是你可以這樣做，來標記 +公司內部的過程，或者只是指出關於簽署的一些特殊細節。 - [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] +作者簽署之後的任何其他簽署（Signed-off-by:'s）均來自處理和傳遞補丁的人員，但 +未參與其開發。簽署鏈應當反映補丁傳播到維護者並最終傳播到Linus所經過的 **真實** +路徑，首個簽署指明單個作者的主要作者身份。 -12）何時使用Acked-by:，CC:，和Co-Developed by: ----------------------------------------------- +何時使用Acked-by:，CC:，和Co-Developed by: +------------------------------------------ -Singed-off-by: 標記表示簽名者參與了補丁的開發，或者他/她在補丁的傳遞路徑中。 +Singed-off-by: 標籤表示簽名者參與了補丁的開發，或者他/她在補丁的傳遞路徑中。 -如果一個人沒有直接參與補丁的準備或處理，但希望表示並記錄他們對補丁的批准， -那麼他們可以要求在補丁的變更日誌中添加一個 Acked-by: +如果一個人沒有直接參與補丁的準備或處理，但希望表示並記錄他們對補丁的批准/贊成， +那麼他們可以要求在補丁的變更日誌中添加一個Acked-by:。 -Acked-by：通常由受影響代碼的維護者使用，當該維護者既沒有貢獻也沒有轉發補丁時。 +Acked-by: 通常由受影響代碼的維護者使用，當該維護者既沒有貢獻也沒有轉發補丁時。 -Acked-by: 不像簽字人那樣正式。這是一個記錄，確認人至少審查了補丁，並表示接受。 -因此，補丁合併有時會手動將Acker的「Yep，looks good to me」轉換爲 Acked-By：（但 +Acked-by: 不像簽署那樣正式。這是一個記錄，確認人至少審閱了補丁，並表示接受。 +因此，補丁合併有時會手動將Acker的“Yep，looks good to me”轉換爲 Acked-By:（但 請注意，通常最好要求一個明確的Ack）。 Acked-by：不一定表示對整個補丁的確認。例如，如果一個補丁影響多個子系統，並且 -有一個：來自一個子系統維護者，那麼這通常表示只確認影響維護者代碼的部分。這裡 -應該仔細判斷。如有疑問，應參考郵件列表檔案中的原始討論。 +有一個來自某個子系統維護者的Acked-By:，那麼這通常表示只確認影響維護者代碼的部 +分。這裏應該仔細判斷。如有疑問，應參考郵件列表存檔中的原始討論。 -如果某人有機會對補丁進行評論，但沒有提供此類評論，您可以選擇在補丁中添加 ``Cc:`` -這是唯一一個標籤，它可以在沒有被它命名的人顯式操作的情況下添加，但它應該表明 -這個人是在補丁上抄送的。討論中包含了潛在利益相關方。 +如果某人本應有機會對補丁進行評論，但沒有提供此類評論，您可以選擇在補丁中添加 +``Cc:`` 這是唯一可以在沒有被該人明確同意的情況下添加的標籤——但它應該表明 +這個人是在補丁上抄送的。此標籤記錄了討論中包含的潛在利益相關方。 Co-developed-by: 聲明補丁是由多個開發人員共同創建的；當幾個人在一個補丁上工 -作時，它用於將屬性賦予共同作者（除了 From: 所賦予的作者之外）。因爲 -Co-developed-by: 表示作者身份，所以每個共同開發人：必須緊跟在相關合作作者的 -簽名之後。標準的簽核程序要求：標記的簽核順序應儘可能反映補丁的時間歷史，而不 -管作者是通過 From ：還是由 Co-developed-by: 共同開發的。值得注意的是，最後一 -個簽字人：必須始終是提交補丁的開發人員。 +作時，它用於給出共同作者（除了From:所給出的作者之外）。因爲Co-developed-by: +表示作者身份，所以每個Co-developed-by:必須緊跟在相關合作作者的簽署之後。標準 +簽署程序要求Singed-off-by:標籤的順序應儘可能反映補丁的時間歷史，無論作者是通 +過From:還是Co-developed-by:表明。值得注意的是，最後一個Singed-off-by:必須是 +提交補丁的開發人員。 -注意，當作者也是電子郵件標題「發件人：」行中列出的人時，「From: 」 標記是可選的。 +注意，如果From:作者也是電子郵件標題的From:行中列出的人，則From:標籤是可選的。 -作者提交的補丁程序示例:: +被From:作者提交的補丁示例:: @@ -423,7 +375,7 @@ Co-developed-by: 表示作者身份，所以每個共同開發人：必須緊跟 Signed-off-by: Second Co-Author Signed-off-by: From Author -合作開發者提交的補丁示例:: +被合作開發者提交的補丁示例:: From: From Author @@ -436,106 +388,115 @@ Co-developed-by: 表示作者身份，所以每個共同開發人：必須緊跟 Signed-off-by: Submitting Co-Author -13）使用報告人：、測試人：、審核人：、建議人：、修復人： --------------------------------------------------------- +使用Reported-by:、Tested-by:、Reviewed-by:、Suggested-by:和Fixes: +----------------------------------------------------------------- Reported-by: 給那些發現錯誤並報告錯誤的人致謝，它希望激勵他們在將來再次幫助 -我們。請注意，如果bug是以私有方式報告的，那麼在使用Reported-by標記之前，請 -先請求權限。 +我們。請注意，如果bug是以私有方式報告的，那麼在使用Reported-by標籤之前，請 +先請求許可。此標籤是爲Bug設計的；請不要將其用於感謝功能請求。 -Tested-by: 標記表示補丁已由指定的人（在某些環境中）成功測試。這個標籤通知 -維護人員已經執行了一些測試，爲將來的補丁提供了一種定位測試人員的方法，並確 -保測試人員的信譽。 +Tested-by: 標籤表示補丁已由指定的人（在某些環境中）成功測試。這個標籤通知 +維護人員已經執行了一些測試，爲將來的補丁提供了一種定位測試人員的方法，並彰顯測試人員的功勞。 -Reviewed-by：相反，根據審查人的聲明，表明該補丁已被審查並被認爲是可接受的： +Reviewed-by：根據審閱者的監督聲明，表明該補丁已被審閱並被認爲是可接受的： -審查人的監督聲明 +審閱者的監督聲明 ^^^^^^^^^^^^^^^^ -通過提供我的 Reviewed-by，我聲明： +通過提供我的Reviewed-by:標籤，我聲明： - (a) 我已經對這個補丁進行了一次技術審查，以評估它是否適合被包含到 + (a) 我已經對這個補丁進行了一次技術審閱，以評估它是否適合被包含到 主線內核中。 (b) 與補丁相關的任何問題、顧慮或問題都已反饋給提交者。我對提交者對 我的評論的回應感到滿意。 - (c) 雖然這一提交可能會改進一些東西，但我相信，此時，（1）對內核 + (c) 雖然這一提交可能仍可被改進，但我相信，此時，（1）對內核 進行了有價值的修改，（2）沒有包含爭論中涉及的已知問題。 - (d) 雖然我已經審查了補丁並認爲它是健全的，但我不會（除非另有明確 - 說明）作出任何保證或保證它將在任何給定情況下實現其規定的目的 + (d) 雖然我已經審閱了補丁並認爲它是健全的，但我不會（除非另有明確 + 說明）作出任何保證或擔保它會在任何給定情況下實現其規定的目的 或正常運行。 -Reviewed-by 是一種觀點聲明，即補丁是對內核的適當修改，沒有任何遺留的嚴重技術 -問題。任何感興趣的審閱者（完成工作的人）都可以爲一個補丁提供一個 Review-by -標籤。此標籤用於向審閱者提供致謝，並通知維護者已在修補程序上完成的審閱程度。 -Reviewed-by: 當由已知了解主題區域並執行徹底檢查的審閱者提供時，通常會增加 +Reviewed-by是一種觀點聲明，即補丁是對內核的適當修改，沒有任何遺留的嚴重技術 +問題。任何感興趣的審閱者（完成工作的人）都可以爲一個補丁提供一個Reviewed-by +標籤。此標籤用於向審閱者提供致謝，並通知維護者補丁的審閱進度。 +當Reviewed-by:標籤由已知了解主題區域並執行徹底檢查的審閱者提供時，通常會增加 補丁進入內核的可能性。 +一旦從測試人員或審閱者的“Tested-by”和“Reviewed-by”標籤出現在郵件列表中， +作者應在發送下一個版本時將其添加到適用的補丁中。但是，如果補丁在以下版本中發 +生了實質性更改，這些標籤可能不再適用，因此應該刪除。通常，在補丁更改日誌中 +（在 ``---`` 分隔符之後）應該提到刪除某人的測試者或審閱者標籤。 + Suggested-by: 表示補丁的想法是由指定的人提出的，並確保將此想法歸功於指定的 -人。請注意，未經許可，不得添加此標籤，特別是如果該想法未在公共論壇上發布。 -這就是說，如果我們勤快地致謝我們的創意者，他們很有希望在未來得到鼓舞，再次 +人。請注意，未經許可，不得添加此標籤，特別是如果該想法未在公共論壇上發佈。 +也就是說，如果我們勤快地致謝創意提供者，他們將受到鼓舞，很有希望在未來再次 幫助我們。 -Fixes: 指示補丁在以前的提交中修復了一個問題。它可以很容易地確定錯誤的來源， -這有助於檢查錯誤修復。這個標記還幫助穩定內核團隊確定應該接收修復的穩定內核 -版本。這是指示補丁修復的錯誤的首選方法。請參閱 :ref:`tw_describe_changes` -描述您的更改以了解更多詳細信息。 +Fixes: 指示補丁修復了之前提交的一個問題。它可以便於確定錯誤的來源，這有助於 +檢查錯誤修復。這個標籤還幫助穩定內核團隊確定應該接收修復的穩定內核版本。這是 +指示補丁修復的錯誤的首選方法。請參閱 :ref:`zh_describe_changes` 瞭解更多信息。 -.. _tw_the_canonical_patch_format: +.. note:: -12）標準補丁格式 ----------------- + 附加Fixes:標籤不會改變穩定內核規則流程，也不改變所有穩定版補丁抄送 + stable@vger.kernel.org的要求。有關更多信息，請閱讀 + Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。 + +.. _zh_the_canonical_patch_format: + +標準補丁格式 +------------ 本節描述如何格式化補丁本身。請注意，如果您的補丁存儲在 ``Git`` 存儲庫中，則 -可以使用 ``git format-patch`` 進行正確的補丁格式設置。但是，這些工具無法創建 +可以使用 ``git format-patch`` 進行正確的補丁格式化。但是，這些工具無法創建 必要的文本，因此請務必閱讀下面的說明。 -標準的補丁，標題行是:: +標準的補丁標題行是:: Subject: [PATCH 001/123] 子系統:一句話概述 -標準補丁的信體存在如下部分： +標準補丁的信體包含如下部分： - - 一個 "from" 行指出補丁作者。後跟空行（僅當發送修補程序的人不是作者時才需要）。 + - 一個 ``from`` 行指出補丁作者。後跟空行（僅當發送補丁的人不是作者時才需要）。 - - 解釋的正文，行以75列包裝，這將被複製到永久變更日誌來描述這個補丁。 + - 說明文字，每行最長75列，這將被複制到永久變更日誌來描述這個補丁。 - 一個空行 - - 上面描述的「Signed-off-by」 行，也將出現在更改日誌中。 + - 上述的 ``Signed-off-by:`` 行，也將出現在更改日誌中。 - 只包含 ``---`` 的標記線。 - - 任何其他不適合放在變更日誌的注釋。 + - 任何其他不適合放在變更日誌的註釋。 - 實際補丁（ ``diff`` 輸出）。 -標題行的格式，使得對標題行按字母序排序非常的容易 - 很多 e-mail 客戶端都 -可以支持 - 因爲序列號是用零填充的，所以按數字排序和按字母排序是一樣的。 +標題行的格式，使得對標題行按字母序排序非常的容易——很多郵件客戶端都 +可以支持——因爲序列號是用零填充的，所以按數字排序和按字母排序是一樣的。 -e-mail 標題中的「子系統」標識哪個內核子系統將被打補丁。 +郵件標題中的“子系統”標識哪個內核子系統將被打補丁。 -e-mail 標題中的「一句話概述」扼要的描述 e-mail 中的補丁。「一句話概述」 -不應該是一個文件名。對於一個補丁系列（「補丁系列」指一系列的多個相關補 -丁），不要對每個補丁都使用同樣的「一句話概述」。 +郵件標題中的“一句話概述”扼要的描述郵件中的補丁。“一句話概述” +不應該是一個文件名。對於一個補丁系列（“補丁系列”指一系列的多個相關補 +丁），不要對每個補丁都使用同樣的“一句話概述”。 -記住 e-mail 的「一句話概述」會成爲該補丁的全局唯一標識。它會蔓延到 git -的改動記錄里。然後「一句話概述」會被用在開發者的討論里，用來指代這個補 -丁。用戶將希望通過 google 來搜索"一句話概述"來找到那些討論這個補丁的文 +記住郵件的“一句話概述”會成爲該補丁的全局唯一標識。它會進入 ``git`` +的改動記錄裏。然後“一句話概述”會被用在開發者的討論裏，用來指代這個補 +丁。用戶將希望通過搜索引擎搜索“一句話概述”來找到那些討論這個補丁的文 章。當人們在兩三個月後使用諸如 ``gitk`` 或 ``git log --oneline`` 之類 的工具查看數千個補丁時，也會很快看到它。 出於這些原因，概述必須不超過70-75個字符，並且必須描述補丁的更改以及爲 -什麼需要補丁。既要簡潔又要描述性很有挑戰性，但寫得好的概述應該這樣做。 +什麼需要補丁。既要簡潔又要描述性很有挑戰性，但寫得好的概述應該這樣。 -概述的前綴可以用方括號括起來：「Subject: [PATCH ...] <概述>」。標記 +概述的前綴可以用方括號括起來：“Subject: [PATCH ...] <概述>”。標記 不被視爲概述的一部分，而是描述應該如何處理補丁。如果補丁的多個版本已發 -送出來以響應評審（即「v1，v2，v3」）或「rfc」，以指示評審請求，那麼通用標記 -可能包括版本描述符。如果一個補丁系列中有四個補丁，那麼各個補丁可以這樣 -編號：1/4、2/4、3/4、4/4。這可以確保開發人員了解補丁應用的順序，並且他們 +送出來以響應評審（即“v1，v2，v3”）則必須包含版本號，或包含“RFC”以指示 +評審請求。如果一個補丁系列中有四個補丁，那麼各個補丁可以這樣編號：1/4、2/4、 +3/4、4/4。這可以確保開發人員瞭解補丁應用的順序，且 已經查看或應用了補丁系列中的所有補丁。 一些標題的例子:: @@ -543,95 +504,134 @@ e-mail 標題中的「一句話概述」扼要的描述 e-mail 中的補丁。 Subject: [patch 2/5] ext2: improve scalability of bitmap searching Subject: [PATCHv2 001/207] x86: fix eflags tracking -"From" 行是信體裡的最上面一行，具有如下格式： +``From`` 行是信體裏的最上面一行，具有如下格式:: + From: Patch Author -"From" 行指明在永久改動日誌里，誰會被確認爲作者。如果沒有 "From" 行，那 -麼郵件頭裡的 "From: " 行會被用來決定改動日誌中的作者。 +``From`` 行指明在永久改動日誌裏，誰會被確認爲作者。如果沒有 ``From`` 行，那 +麼郵件頭裏的 ``From:`` 行會被用來決定改動日誌中的作者。 + +說明文字將會被提交到永久的源代碼改動日誌裏，因此應針對那些早已經不記得和這 +個補丁相關的討論細節的讀者。包括補丁處理的故障症狀（內核日誌消息、oops消息 +等），這對於可能正在搜索提交日誌以查找適用補丁的人特別有用。文本應該寫得如 +此詳細，以便在數週、數月甚至數年後閱讀時，能夠爲讀者提供所需的細節信息，以 +掌握創建補丁的 **原因** 。 -說明的主題將會被提交到永久的原始碼改動日誌里，因此對那些早已經不記得和 -這個補丁相關的討論細節的有能力的讀者來說，是有意義的。包括補丁程序定位 -錯誤的（內核日誌消息、OOPS消息等）症狀，對於搜索提交日誌以尋找適用補丁的人 -尤其有用。如果一個補丁修復了一個編譯失敗，那麼可能不需要包含所有編譯失敗； +如果一個補丁修復了一個編譯失敗，那麼可能不需要包含 *所有* 編譯失敗； 只要足夠讓搜索補丁的人能夠找到它就行了。與概述一樣，既要簡潔又要描述性。 -"---" 標記行對於補丁處理工具要找到哪裡是改動日誌信息的結束，是不可缺少 +``---`` 標記行對於補丁處理工具要找到哪裏是改動日誌信息的結束，是不可缺少 的。 -對於 "---" 標記之後的額外註解，一個好的用途就是用來寫 diffstat，用來顯 -示修改了什麼文件和每個文件都增加和刪除了多少行。diffstat 對於比較大的補 -丁特別有用。其餘那些只是和時刻或者開發者相關的註解，不合適放到永久的改 -動日誌里的，也應該放這裡。 -使用 diffstat的選項 "-p 1 -w 70" 這樣文件名就會從內核原始碼樹的目錄開始 -，不會占用太寬的空間（很容易適合80列的寬度，也許會有一些縮進。） +對於 ``---`` 標記之後的額外註解，一個好的用途就是用來寫 ``diffstat`` ，用來顯 +示修改了什麼文件和每個文件都增加和刪除了多少行。 ``diffstat`` 對於比較大的補 +丁特別有用。 +使用 ``diffstat`` 的選項 ``-p 1 -w 70`` 這樣文件名就會從內核源代碼樹的目錄開始 +，不會佔用太寬的空間（很容易適合80列的寬度，也許會有一些縮進。） +（ ``git`` 默認會生成合適的diffstat。） -在後面的參考資料中能看到適當的補丁格式的更多細節。 +其餘那些只適用於當時或者與維護者相關的註解，不合適放到永久的改動日誌裏的，也 +應該放這裏。較好的例子就是 ``補丁更改記錄`` ，記錄了v1和v2版本補丁之間的差異。 -.. _tw_explicit_in_reply_to: +請將此信息放在將變更日誌與補丁的其餘部分分隔開的 ``---`` 行 **之後** 。版本 +信息不是提交到git樹的變更日誌的一部分。只是供審閱人員使用的附加信息。如果將 +其放置在提交標記上方，則需要手動交互才能將其刪除。如果它位於分隔線以下，則在 +應用補丁時會自動剝離:: -15) 明確回覆郵件頭(In-Reply-To) -------------------------------- + + ... + Signed-off-by: Author + --- + V2 -> V3: Removed redundant helper function + V1 -> V2: Cleaned up coding style and addressed review comments -手動添加回復補丁的的標題頭(In-Reply_To:) 是有幫助的（例如，使用 ``git send-email`` ） -將補丁與以前的相關討論關聯起來，例如，將bug修復程序連結到電子郵件和bug報告。 -但是，對於多補丁系列，最好避免在回復時使用連結到該系列的舊版本。這樣， -補丁的多個版本就不會成爲電子郵件客戶端中無法管理的引用序列。如果連結有用， -可以使用 https://lore.kernel.org/ 重定向器（例如，在封面電子郵件文本中） -連結到補丁系列的早期版本。 + path/to/file | 5+++-- + ... + +在後面的參考資料中能看到正確補丁格式的更多細節。 -16) 發送git pull請求 --------------------- +.. _zh_backtraces: -如果您有一系列補丁，那麼讓維護人員通過git pull操作將它們直接拉入子系統存儲 -庫可能是最方便的。但是，請注意，從開發人員那裡獲取補丁比從郵件列表中獲取補 -丁需要更高的信任度。因此，許多子系統維護人員不願意接受請求，特別是來自新的 -未知開發人員的請求。如果有疑問，您可以在封面郵件中使用pull 請求作爲補丁系列 -正常發布的一個選項，讓維護人員可以選擇使用其中之一。 +提交消息中的回溯（Backtraces） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +回溯有助於記錄導致問題的調用鏈。然而，並非所有回溯都有幫助。例如，早期引導調 +用鏈是獨特而明顯的。而逐字複製完整的dmesg輸出則會增加時間戳、模塊列表、寄存 +器和堆棧轉儲等分散注意力的信息。 + +因此，最有用的回溯應該從轉儲中提取相關信息，以更容易集中在真實問題上。下面是 +一個剪裁良好的回溯示例:: + + unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) + at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Call Trace: + mba_wrmsr + update_domains + rdtgroup_mkdir + +.. _zh_explicit_in_reply_to: + +明確回覆郵件頭（In-Reply-To） +----------------------------- + +手動添加回復補丁的的郵件頭（In-Reply_To:）是有用的（例如，使用 ``git send-email`` ）， +可以將補丁與以前的相關討論關聯起來，例如，將bug補丁鏈接到電子郵件和bug報告。 +但是，對於多補丁系列，最好避免在回覆時使用鏈接到該系列的舊版本。這樣， +補丁的多個版本就不會成爲電子郵件客戶端中無法管理的引用樹。如果鏈接有用， +可以使用 https://lore.kernel.org/ 重定向器（例如，在封面電子郵件文本中） +鏈接到補丁系列的早期版本。 -pull 請求的主題行中應該有[Git Pull]。請求本身應該在一行中包含存儲庫名稱和 -感興趣的分支；它應該看起來像:: +給出基礎樹信息 +-------------- - Please pull from +當其他開發人員收到您的補丁並開始審閱時，知道應該將您的工作放到代碼樹歷史記錄 +中的什麼位置通常很有用。這對於自動化持續集成流水（CI）特別有用，這些流水線試 +圖運行一系列測試，以便在維護人員開始審閱之前確定提交的質量。 - git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus +如果您使用 ``git format-patch`` 生成補丁，則可以通過 ``--base`` 標誌在提交中 +自動包含基礎樹信息。使用此選項最簡單、最方便的方法是配合主題分支:: - to get these changes: + $ git checkout -t -b my-topical-branch master + Branch 'my-topical-branch' set up to track local branch 'master'. + Switched to a new branch 'my-topical-branch' + [perform your edits and commits] -pull 請求還應該包含一條整體消息，說明請求中將包含什麼，一個補丁本身的 ``Git shortlog`` -以及一個顯示補丁系列整體效果的 ``diffstat`` 。當然，將所有這些信息收集在一起 -的最簡單方法是讓 ``git`` 使用 ``git request-pull`` 命令爲您完成這些工作。 + $ git format-patch --base=auto --cover-letter -o outgoing/ master + outgoing/0000-cover-letter.patch + outgoing/0001-First-Commit.patch + outgoing/... -一些維護人員（包括Linus）希望看到來自已簽名提交的請求；這增加了他們對你的 -請求信心。特別是，在沒有簽名標籤的情況下，Linus 不會從像 Github 這樣的公共 -託管站點拉請求。 +當你編輯 ``outgoing/0000-cover-letter.patch`` 時，您會注意到在它的最底部有一 +行 ``base-commit:`` 尾註，它爲審閱者和CI工具提供了足夠的信息以正確執行 +``git am`` 而不必擔心衝突:: -創建此類簽名的第一步是生成一個 GNRPG 密鑰，並由一個或多個核心內核開發人員對 -其進行簽名。這一步對新開發人員來說可能很困難，但沒有辦法繞過它。參加會議是 -找到可以簽署您的密鑰的開發人員的好方法。 + $ git checkout -b patch-review [base-commit-id] + Switched to a new branch 'patch-review' + $ git am patches.mbox + Applying: First Commit + Applying: ... -一旦您在Git 中準備了一個您希望有人拉的補丁系列，就用 ``git tag -s`` 創建一 -個簽名標記。這將創建一個新標記，標識該系列中的最後一次提交，並包含用您的私 -鑰創建的簽名。您還可以將changelog樣式的消息添加到標記中；這是一個描述拉請求 -整體效果的理想位置。 +有關此選項的更多信息，請參閱 ``man git-format-patch`` 。 -如果維護人員將要從中提取的樹不是您正在使用的存儲庫，請不要忘記將已簽名的標記 -顯式推送到公共樹。 +.. note:: -生成拉請求時，請使用已簽名的標記作爲目標。這樣的命令可以實現:: + ``--base`` 功能是在2.9.0版git中引入的。 - git request-pull master git://my.public.tree/linux.git my-signed-tag +如果您不使用git格式化補丁，仍然可以包含相同的 ``base-commit`` 尾註，以指示您 +的工作所基於的樹的提交哈希。你應該在封面郵件或系列的第一個補丁中添加它，它應 +該放在 ``---`` 行的下面或所有其他內容之後，即只在你的電子郵件簽名之前。 參考文獻 -------- -Andrew Morton, "The perfect patch" (tpp). +Andrew Morton，“完美的補丁”（tpp） -Jeff Garzik, "Linux kernel patch submission format". +Jeff Garzik，“Linux內核補丁提交格式” -Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". +Greg Kroah-Hartman，“如何惹惱內核子系統維護人員” @@ -644,17 +644,16 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". -NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! +不！！！別再發巨型補丁炸彈給linux-kernel@vger.kernel.org的人們了！ -Kernel Documentation/process/coding-style.rst: - :ref:`Documentation/translations/zh_TW/process/coding-style.rst ` +內核 Documentation/translations/zh_CN/process/coding-style.rst -Linus Torvalds's mail on the canonical patch format: +Linus Torvalds關於標準補丁格式的郵件 -Andi Kleen, "On submitting kernel patches" - Some strategies to get difficult or controversial changes in. +Andi Kleen，“提交補丁之路” + 一些幫助合入困難或有爭議的變更的策略。 http://halobates.de/on-submitting-patches.pdf diff --git a/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst b/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst index 097fe80352cb..36d2e3cb18e3 100644 --- a/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst +++ b/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst @@ -19,20 +19,20 @@ 時奎亮 Alex Shi 胡皓文 Hu Haowen -爲什麼不應該使用「volatile」類型 -================================ +爲什麼不應該使用“volatile”類型 +============================== -C程式設計師通常認爲volatile表示某個變量可以在當前執行的線程之外被改變；因此，在內核 -中用到共享數據結構時，常常會有C程式設計師喜歡使用volatile這類變量。換句話說，他們經 +C程序員通常認爲volatile表示某個變量可以在當前執行的線程之外被改變；因此，在內核 +中用到共享數據結構時，常常會有C程序員喜歡使用volatile這類變量。換句話說，他們經 常會把volatile類型看成某種簡易的原子變量，當然它們不是。在內核中使用volatile幾 乎總是錯誤的；本文檔將解釋爲什麼這樣。 理解volatile的關鍵是知道它的目的是用來消除優化，實際上很少有人真正需要這樣的應 -用。在內核中，程式設計師必須防止意外的並發訪問破壞共享的數據結構，這其實是一個完全 -不同的任務。用來防止意外並發訪問的保護措施，可以更加高效的避免大多數優化相關的 +用。在內核中，程序員必須防止意外的併發訪問破壞共享的數據結構，這其實是一個完全 +不同的任務。用來防止意外併發訪問的保護措施，可以更加高效的避免大多數優化相關的 問題。 -像volatile一樣，內核提供了很多原語來保證並發訪問時的數據安全（自旋鎖, 互斥量,內 +像volatile一樣，內核提供了很多原語來保證併發訪問時的數據安全（自旋鎖, 互斥量,內 存屏障等等），同樣可以防止意外的優化。如果可以正確使用這些內核原語，那麼就沒有 必要再使用volatile。如果仍然必須使用volatile，那麼幾乎可以肯定在代碼的某處有一 個bug。在正確設計的內核代碼中，volatile能帶來的僅僅是使事情變慢。 @@ -46,8 +46,8 @@ C程式設計師通常認爲volatile表示某個變量可以在當前執行的 如果所有的代碼都遵循加鎖規則，當持有the_lock的時候，不可能意外的改變shared_data的 值。任何可能訪問該數據的其他代碼都會在這個鎖上等待。自旋鎖原語跟內存屏障一樣—— 它 -們顯式的用來書寫成這樣 —— 意味著數據訪問不會跨越它們而被優化。所以本來編譯器認爲 -它知道在shared_data裡面將有什麼，但是因爲spin_lock()調用跟內存屏障一樣，會強制編 +們顯式的用來書寫成這樣 —— 意味着數據訪問不會跨越它們而被優化。所以本來編譯器認爲 +它知道在shared_data裏面將有什麼，但是因爲spin_lock()調用跟內存屏障一樣，會強制編 譯器忘記它所知道的一切。那麼在訪問這些數據時不會有優化的問題。 如果shared_data被聲名爲volatile，鎖操作將仍然是必須的。就算我們知道沒有其他人正在 @@ -55,13 +55,13 @@ C程式設計師通常認爲volatile表示某個變量可以在當前執行的 shared_data不是volatile的。在處理共享數據的時候，適當的鎖操作可以不再需要 volatile —— 並且是有潛在危害的。 -volatile的存儲類型最初是爲那些內存映射的I/O寄存器而定義。在內核里，寄存器訪問也應 -該被鎖保護，但是人們也不希望編譯器「優化」臨界區內的寄存器訪問。內核里I/O的內存訪問 +volatile的存儲類型最初是爲那些內存映射的I/O寄存器而定義。在內核裏，寄存器訪問也應 +該被鎖保護，但是人們也不希望編譯器“優化”臨界區內的寄存器訪問。內核裏I/O的內存訪問 是通過訪問函數完成的；不贊成通過指針對I/O內存的直接訪問，並且不是在所有體系架構上 都能工作。那些訪問函數正是爲了防止意外優化而寫的，因此，再說一次，volatile類型不 是必需的。 -另一種引起用戶可能使用volatile的情況是當處理器正忙著等待一個變量的值。正確執行一 +另一種引起用戶可能使用volatile的情況是當處理器正忙着等待一個變量的值。正確執行一 個忙等待的方法是:: while (my_variable != what_i_want) @@ -74,14 +74,14 @@ cpu_relax()調用會降低CPU的能量消耗或者讓位於超線程雙處理器 - 在一些體系架構的系統上，允許直接的I/0內存訪問，那麼前面提到的訪問函數可以使用 volatile。基本上，每一個訪問函數調用它自己都是一個小的臨界區域並且保證了按照 - 程式設計師期望的那樣發生訪問操作。 + 程序員期望的那樣發生訪問操作。 - 某些會改變內存的內聯彙編代碼雖然沒有什麼其他明顯的附作用，但是有被GCC刪除的可 能性。在彙編聲明中加上volatile關鍵字可以防止這種刪除操作。 - Jiffies變量是一種特殊情況，雖然每次引用它的時候都可以有不同的值，但讀jiffies 變量時不需要任何特殊的加鎖保護。所以jiffies變量可以使用volatile，但是不贊成 - 其他跟jiffies相同類型變量使用volatile。Jiffies被認爲是一種「愚蠢的遺留物" + 其他跟jiffies相同類型變量使用volatile。Jiffies被認爲是一種“愚蠢的遺留物" （Linus的話）因爲解決這個問題比保持現狀要麻煩的多。 - 由於某些I/0設備可能會修改連續一致的內存,所以有時,指向連續一致內存的數據結構 @@ -92,9 +92,9 @@ cpu_relax()調用會降低CPU的能量消耗或者讓位於超線程雙處理器 bug並且需要對這樣的代碼額外仔細檢查。那些試圖使用volatile的開發人員需要退一步想想 他們真正想實現的是什麼。 -非常歡迎刪除volatile變量的補丁 － 只要證明這些補丁完整的考慮了並發問題。 +非常歡迎刪除volatile變量的補丁 － 只要證明這些補丁完整的考慮了併發問題。 -注釋 +註釋 ---- [1] https://lwn.net/Articles/233481/ -- 2.34.1