| 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 之类的页面。
在大多数情况下，不应更改这些链接；不过，也可能存在例外情况，例如当 Component 框架版本更改时。通过 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
此重定向会导致
实现
创建三项更改：
- 包含新的
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/。
缺点、替代方案和未知情况
不适用
早期技术和参考资料
链接缩短器的示例，例如：