README.fuchsia 檔案語法

README.fuchsia 檔案用於註解第三方來源程式庫，並提供一些實用的中繼資料，例如程式碼來源、版本、授權和安全性重要標籤。

這些檔案的格式包含一或多個指令行，後接非結構化說明和附註。

指令由行首的指令關鍵字組成，後面緊接著半形冒號和值，值會延伸至行尾。值可能含有周圍的空白字元，指令前後或之間可能會出現空白行。

下文將說明多項指令，但 README.fuchsia 檔案中可能會出現其他指令，而使用這些檔案的軟體不應將不明指令視為錯誤。同樣地，這類軟體應不區分大小寫，比對指令關鍵字。

說明行是選用項目，且須遵循 Description 指令，該指令必須出現在任何非結構化說明文字之前的單獨一行。

語法

file                  := directive-line* description?
directive-line        := directive | blank-line
directive             := keyword ":" SPACE* value SPACE* EOL
value                 := NONBLANK ANYCHAR*
description           := description-directive description-line*
description-directive := "Description:" SPACE* EOL
description-line      := ANYCHAR* EOL
keyword               := [A-Za-z0-9][A-Za-z0-9 ]*
blank-line            := SPACE* EOL
SPACE                 := any whitespace character
EOL                   := end of line character
NONBLANK              := any non-whitespace, non-EOL character
ANYCHAR               := any character but EOL

需求條件

指令關鍵字及其定義如下。本節會綜合說明每個 README.fuchsia 應有的內容，並隨著時間推移持續更新：

  • 為進行安全漏洞掃描，每個 README.fuchsia 都必須提供下列最新資訊：
    • URL 和 Revision：如果是 Git 存放區，就必須選擇這個選項。 或
    • CPEPrefix和Version

這項資訊可為安全漏洞掃描器提供足夠的資訊，以便準確掃描這些依附元件。

  • 為進行授權，每個 README.fuchsia 都必須保留以下最新資訊：
    • License和License File

常見指令關鍵字

常見的指令關鍵字包括：

  • Name

    套件的描述性名稱。

    Name: OpenSSH

  • Short Name

    (選用) 套件的發布名稱 (例如 libxml、openssl 等)。

    Short Name: openssh

  • URL

    (必要) 套件所在的網址，也就是 Git 存放區的可複製網址、套件管理員的套件管理員網址，或此處列出的網址類型 (如 AutoVM 的中繼資料原型所示)。如果沒有上游，請使用「This is the canonical public repository」。如果是來自 Google 內部存放區的套件，請使用「Google Internal」。 如有需要，可重複使用這項指令來加入多個網址。

    示例： URL: https://github.com/openssh/openssh-portable

    URL: https://chromium.googlesource.com/chromium/src/

  • Revision

    (如果依附元件的上游是 Git 存放區，則為必要；如果上游不是 Git 存放區，且提供版本或日期，則為選用)。修訂版本通常是 git 雜湊。如果依附元件是由自動捲動器或指令碼管理，請務必確保升級程序也會更新 README.fuchsia 檔案，並使用正確的修訂版本。

    Revision: 8950d99ba1ba67280fbd1e5445214d2cebe966bb

  • Date

    • 套件更新日期，格式為 YYYY-MM-DD。
    Date: 2018-02-14

  • License

    套件的發布授權。如要瞭解允許的授權政策和其他指引，請參閱 Fuchsia 開放原始碼授權政策。 License: BSD

  • License File

    從 README.fuchsia 檔案到授權檔案的相對路徑。檔案應包含套件授權副本，並對應上方提供的授權。無論是否出貨，所有套件都應包含有效授權。 如有需要，可重複使用這項指令來納入多個檔案。

    License File: LICENSE

  • Security Critical

    yes 或 no 標籤，指出套件是否攸關安全性，有助於評估套件中的安全性錯誤對 Fuchsia 的影響。

    如果套件用於正式環境，且執行下列任一動作，即屬於安全關鍵套件：

    • 接受來自網際網路的不可信輸入內容
    • 剖析或解讀複雜的輸入格式
    • 將資料傳送至網際網路伺服器
    • 收集新資料
    • 影響或設定安全性相關政策 (包括使用者體驗)
    • 以記憶體不安全的語言編寫 (例如：C/C++、Rust，但含有不安全的區塊)

    這是必要指令。

    Security Critical: yes

  • License Android Compatible

    (如果套件未隨附或使用標準表單授權，則為選用) 視套件是否使用與 Android 相容的授權，選擇 yes 或 no。

    License Android Compatible: yes

  • CPEPrefix

    (選用，但如未提供網址和修訂版本，則為必要) 根據搜尋結果，代表上游套件的「通用平台列舉」版本 2.3 (建議) 或 2.2。這項資訊會用於回報上游軟體套件中的已知安全漏洞，確保我們能合併這些安全漏洞的修正程式。請務必根據該套件的 CPE 標準格式，使用最接近的適用上游版本。例如 cpe:/a:xmlsoft:libxslt:1.0.10。如果套件沒有 CPE，請指定「unknown」。如果您使用的是介於兩個公開版本之間的修補或修改版本，請「向下捨入」至較低的公開版本。

  • Version

    (如果使用 CPEPrefix 進行安全漏洞掃描，則為必要項目) 這通常是 Git 標記。如果不是 Git，則應為可搜尋的套件版本號碼 (如果套件沒有版本，或版本是依日期或修訂版本而定，這個欄位應為「不適用」，且修訂版本或日期應列舉在適當的欄位中)。如果依附元件是由自動捲動器或指令碼管理，請務必確保升級程序也會更新 README.fuchsia 檔案，並使用正確的版本。

    Version: 7.6

  • Description

    簡短說明套件內容和用途。

    Description:

This package does x, y, and z.

  • Local Modifications

    列舉對上述出貨版本套件所做的任何本機變更。

    如果第三方套件中的檔案 (例如在 Git 簽出期間擷取的檔案) 未經修改，請在此處輸入「None」(不含外圍引號)。

    Local Modifications:

Added README.fuchsia.
Ported build rules from CMake to GN.

參考資料

README.fuchsia 格式是以 Chromium 的 README.chromium 格式為準。 請參閱 Chromium 的 adding_to_third_party.md 做為補充參考資料。