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

此重定向会导致 并指向 。

实现

创建三个更改：

• 一个 Gerrit 更改，其中包含新的 docs/go 目录以及 _redirects.yaml、README.md 和 OWNERS 文件。
• 用于更新 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/