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

摘要

允許使用較短、有意義且持久的連結，連結至特定 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、curtigalloway。

諮詢對象：選舉委員會成員。

意見交流：已將 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 檔案的 gerrit 變更。
• 更新 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/