RFC-0125：Fuchsia.dev 上的短連結

摘要

允許使用更短、有意義且持久的連結，連至特定 Fuchsia 構件。這些短連結可確保連結不會隨著時間而失效。

建議格式為 fuchsia.dev/go/ ，可對應至任何 fuchsia.dev 文件或 Fuchsia 來源樹狀結構中的特定檔案。

舉例來說，fuchsia.dev/go/components 可能會重新導向至 fuchsia.dev/fuchsia-src/concepts/components/v2 等頁面。

在大多數情況下，這些連結不應變更；但例外情形可能存在，例如 Component 架構版本變更時。透過 go/link，您可以在這些版本變更之間順利轉換。

提振精神

縮短連結後，即可用於評量標準、規格、說明文件、常見問題、支援的硬體等。這類範例也有助於瞭解版本更新，例如 Components v2。

這也有助於 Fuchsia 特定核心部分的版本控管，例如元件。

利害關係人

導師：hjfreyer。

審查者：mkearney、curtisgalloway。

諮詢對象：FEC 成員。

社交化：RFC 草案已與技術寫作團隊分享。

設計

設計方式是在 docs/go/ 的來源樹狀結構中建立目錄，以便放置 _redirects.yaml 檔案。

這個目錄會包含 README.md 檔案，說明如何使用重新導向。此外，您還會收到 OWNERS 檔案，可供您審查並核准新的短連結。OWNERS 也必須核准現有 go 連結的任何可能變更。只有在非常特殊的情況下，才應核准這些變更，例如取代核心概念，像是新版元件架構。

重新導向的格式如下：

- from: /docs/go/<keyword>
  to: <path in source tree>

範例：

- from: /docs/go/drivers
  to: /docs/reference/hardware/drivers.md

這項重新導向會產生 ，並指向 。

實作

建立三項變更：

• Gerrit 變更，其中包含新的 docs/go 目錄，以及 _redirects.yaml、README.md 和 OWNERS 檔案。
• 更新 doc_checker 以進行測試的 Gerrit 變更。請參閱「測試」一節。
• fuchsia.dev 的整體重新導向，可將 fuchsia.dev/fuchsia-src/go/ 重新導向至 fuchsia.dev/go。fuchsia/src/go/ 是 fuchsia.dev 上的 docs/go 路徑。

效能

這會導致重新導向，因此延遲時間會稍微增加。

人體工學

這可讓貢獻者為 Fuchsia 文件建立容易記住的關鍵字。

回溯相容性

不適用。

安全性考量

從技術上來說，您可以在 /docs/ 目錄的任何子目錄中新增 _redirects.yaml 檔案，以進行重新導向。不過，_redirects.yaml 檔案的範圍僅限於檔案所在的目錄，因此應該不會發生 fuchsia.dev 的其他部分遭到重新導向的問題。

這項提案會建立 /docs/go/_redirects.yaml 檔案，將重新導向範圍限制為僅限 fuchsia.dev/go/。在背景中，較高層級的重新導向會負責將 fuchsia.dev/fuchsia-src/go 重新導向至 fuchsia.dev/go。請注意，將 Git 存放區移至 fuchsia.dev 後，fuchsia-src/ 目錄會對應至 docs/ 目錄。

隱私權注意事項

不適用。

測試

doc_checker 可擴展驗證以下項目：

• 為避免發生問題，- from: 欄位只有 /docs/go 個路徑。
• to: 連結存在。
• /docs/ 中的其他 .md 檔案未參照失效的 /docs/go/ 連結。
• 連結名稱中不會使用有問題的字詞或詞組。
• 沒有重複的「go」關鍵字。

說明文件

建立 README.md，說明檔案的語法，並包含下列項目：

• 製作短連結的評量標準。請參閱評分標準。舉例來說，如果發生重組，應永久參照的事項。審查員可參考這份評量表，判斷建議連結是否有效。

評分量表

短連結 (fuchsia.dev/go) 應具備耐久性、有意義的名稱，且能引起一般興趣。這些連結是永久連結，且使用平面命名空間，因此建議您仔細考慮每項提案，以限制建立的短連結數量。

審查人員應考量下列因素，核准待處理的短網址要求：

• 建議的連結是否長期適用？連結應能長期使用，因此請確保連結在很長一段時間內仍能引起一般大眾的興趣。

  • 正面示例： 一般 Fuchsia 常見問題頁面或目前支援的硬體清單。雖然這些主題會隨著時間改變，但永遠切合需求。

  • 反面示例： 正在審查的 RFC 提案。提案目前仍有效，但最終會獲得接受或遭到拒絕。如果接受，這可能就是適合參考的短連結主題。

• 連結是否涵蓋一般主題或概念？是否適合廣大觀眾？

  • 正向範例：

    • FIDL 總覽。這是 Fuchsia 使用的基本技術。
    • Fuchsia 安全性模型。這對使用者和開發人員來說都很有意義。

  • 負例：

    • 單一系統呼叫的說明文件。系統呼叫清單的連結會更合適。
    • 透過乙太網路啟動特定型號 NUC 的操作說明。連結至在各類裝置上啟動 Fuchsia 的一般頁面，可吸引更多觀眾。

• 連結是否與現有的易用連結重複，且不太可能變更？

  • 正向示例： 不太可能變更，因此 可能多餘。

• 連結名稱是否具有意義，且符合《尊重他人守則》？短連結當然要短，但不能因此難以理解。

  • 正向示例： 以下兩個示例簡短且具描述性：

    • /docs/go/faq (會顯示為 fuchsia.dev/go/faq)。
    • /docs/go/hardware-specs (轉譯為 fuchsia.dev/go/hardware-specs)。

• to 連結是否指向 /docs/ 目錄內的文件？

  • 正向範例：

    • to: /docs/concepts/software_model.md。

  • 負例：

    • to: http://google.com/。

缺點、替代方案和未知事項

不適用

既有技術和參考資料

例如：

• http://bit.ly/