| RFC-0125：Fuchsia.dev 上的短链接 | |
|---|---|
| 状态 | 已接受 |
| 领域 |
|
| 说明 | 允许将 fuchsia.dev/go/ |
| Gerrit 更改 | |
| 作者 | |
| 审核人 | |
| 提交日期（年-月-日） | 2021-07-09 |
| 审核日期（年-月-日） | 2021-09-01 |
摘要
允许使用简短、有意义且持久的链接，指向特定 Fuchsia 工件这些短链接可确保链接不会随着时间的推移而降级。
建议使用的格式为 fuchsia.dev/go/
例如，fuchsia.dev/go/components 会重定向到某网页 例如 fuchsia.dev/fuchsia-src/concepts/components/v2。
在大多数情况下，不应更改这些链接；不过 异常，例如当组件框架版本更改时。通过 go/link 能够在这些版本更改之间无缝转换。
设计初衷
较短的链接适用于评分准则、规范、 文档、常见问题解答、支持的硬件等。它们也很有用 （例如，组件 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文件。 - Gerrit 变更，用于更新
doc_checker以进行测试。请参阅 测试。 - fuchsia.dev 的总体重定向到重定向 fuchsia.dev/fuchsia-src/go/
访问 fuchsia.dev/go。fuchsia/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) 具有持久性、具有实际意义 名称和名称。这些链接持久且使用 因此最好仔细考虑每个提案 限制创建的短链接的数量。
在决定是否批准待审核的短视频时，审核者应考虑以下因素 关联请求：
提议的链接是否长期有效？ 链接只会持久保存，因此您应该有一定的信心 以确保在很长一段时间内，链接仍受大众欢迎。
正例： 常规 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/。
缺点、替代方案和未知问题
不适用
先验技术和参考资料
链接缩短工具的示例：