RFC-0125：Fuchsia.dev 上的短链接

摘要

允许使用更短、更有意义且持久的链接来指向特定的 Fuchsia 制品。这些短链接可确保链接不会随时间推移而失效。

建议的格式为 fuchsia.dev/go/ ，可映射到任何 fuchsia.dev 文档或 Fuchsia 源代码树中的特定文件。

例如，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

此重定向会生成 并指向 。

实现

创建三个更改：

• 包含新 docs/go 目录以及 _redirects.yaml、README.md 和 OWNERS 文件的 Gerrit 更改。
• 用于更新 doc_checker 以进行测试的 Gerrit 更改。请参阅测试。
• 一个将 fuchsia.dev 重定向到 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/