| RFC-0125：Fchsia.dev 上的 Shortlink | |
|---|---|
| 狀態 | 已接受 |
| 領域 |
|
| 說明 | 允許將 fuchsia.dev/go/ |
| 毛皮變化 | |
| 作者 | |
| 審查人員 | |
| 提交日期 (年-月-日) | 2021-07-09 |
| 審查日期 (年-月-日) | 2021-09-01 |
摘要
允許使用較短、有意義且耐用的 Fuchsia 連結 導致學習失真性這些短連結不會隨著時間降低。
建議的格式為 fuchsia.dev/go/
舉例來說，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檔案。 - 更新
doc_checker以進行測試的暫時性變更。詳情請見 測試。 - fuchsia.dev 重新導向 fuchsia.dev/fuchsia-src/go/ 的整體重新導向
前往 fuchsia.dev/gofuchsia/src/go/ 會是
docs/go的路徑 fuchsia.dev.
成效
這會讓重新導向作業造成些微的延遲時間增加。
人體工學
方便貢獻者輕鬆記住 Fuchsia 的關鍵字 說明文件。
回溯相容性
無可比較；
安全性考量
嚴格說來，您可以將 _redirects.yaml 檔案新增至
進行重新導向的 /docs/ 目錄子目錄。不過，範圍
_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) 採用長期可行的做法，具有實質意義 且只有一般利益這些連結很耐用，而且會使用 扁平的命名空間 因此建議您仔細思考每項提案 來限制已建立的短連結數量。
審查人員應考量下列因素，才能核准待審核的 Shorts 連結要求：
提議的連結是否會長期使用？ 連結設計具有耐用性，因此您應該在合理範圍內 且該連結在一段時間內都會持續引起一般使用者的興趣。
正面範例： 一般 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/。
缺點、替代方案和未知
無
既有藝術品和參考資料
連結短褲的範例，例如：