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

RFC-0125： Fuchsia.dev 上的 Shortlinks
狀態	已接受
區域	開發人員
說明	允許將 fuchsia.dev/go/ 重新導向至特定 Fuchsia 構件。
變更	553175
作者	nickvander@google.com curtisgalloway@google.com
審查人員	curtisgalloway@google.com mkearney@google.com tkilbourn@google.com
提交日期 (年/月)	2021-07-09
審查日期 (年/月)	2021-09-01

摘要

允許使用較短、有意義且耐用的特定 Fuchsia 構件連結。這些短連結可確保連結不會隨著時間降低。

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

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

在大多數情況下，這些連結不應變更，但可能會有例外狀況，例如元件架構版本變更。同時，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

此重新導向會產生 並指向 。

實作

建立三項變更：

• 包含新的 docs/go 目錄以及 _redirects.yaml、README.md 和 OWNERS 檔案的 Adrit 變更。
• 針對測試更新 doc_checker 的地域變更。請參閱「測試」。
• 將 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/。