贡献于 HASS.Agent 文档¶

更易编辑的编辑器

如果你不懂 VSCode 或 git 版本控制的基础知识，请查看这个页面。

Warning

在继续之前，确保你理解 HASS.Agent 客户端版本系统。你可以在这里找到相关信息。

概述¶

HASS.Agent 文档是基于 MKDocs 构建的，MKDocs 是一个基于 Python 的工具，允许你使用简单的 Markdown 编写文档。大部分文档是用 Markdown 编写的，因此易于编辑。但是提交这些编辑并测试它们需要基本的 git 和 GitHub 版本控制知识。

文档版本¶

在文档的顶部，你将找到一个标题版本的选择器。这是一个版本选择器，允许你查看不同版本的文档。你会注意到有两个特殊版本，其余的遵循 *.* 格式：

版本	描述
`beta`	当前文档的 beta 版本，用于测试新功能和编写 HASS.Agent 即将推出的功能的文档。
`latest`	当前 HASS.Agent 的最新发布版本，这也是默认版本。
`.`	文档的旧版本，这些版本不可编辑。这些被称为 `old-versions`。示例：`1.5`

GitHub 结构¶

文档的仓库始终链接在文档的右上角，并且也可以在这里找到。继续在另一个标签页中打开它，以便参考本节内容。

分支概述¶

仓库包含三个分支：

分支	描述
`main`	包含用于维护 `latest`¹ 版本文档的文件。
`beta`	包含正在开发文档下一个发布的文件，这也是文档的 `beta`¹ 版本。
`gh-pages`	包含文档的构建文件，这个仓库不应该被触碰，所有文件都是用 HTML、CSS 和 JS 编写的。在文档构建期间，所有文件都会自动生成。

为什么有两个独立的分支？¶

我们在 GitHub 上使用两个独立的分支，因为它允许我们在修复当前文档问题时工作于文档的新版本。这对我们来说很好，因为我们可以在网上测试新功能并将它们发送给人们，而不会意外破坏 latest¹ 文档。然而，这也产生了一些需要遵循的指南：

如果你想让你的更改应用于文档的所有未来版本，你必须**在 beta 分支中做出这些更改。
对 main 分支所做的任何更改将立即应用于 latest¹ 版本，但是它们不会包含在文档的未来版本中。

如果你想了解为什么存在这些限制，请查看这个部分。

部署文档¶

当 beta 或 main 分支发生合并时，特定的 GitHub 工作流程将运行，自动构建和部署正确的文档版本。因此，你不需要做任何构建或部署。

发布 `beta` 版本¶

当发布 beta¹ 版本作为 latest¹ 版本时，GitHub 的管理员之一将手动触发一个工作流程，该工作流程将部署并构建 beta 分支作为 latest¹ 版本，并且还会为 beta¹ 版本部署一个副本。部署后，将触发合并以将 beta 分支与 main 分支合并。我们将尽最大努力将 main 分支的更改带到 beta 分支，但我们不能保证，这就是为什么存在这个部分的原因。

为什么存在限制？¶

这些限制之所以存在是因为系统的构建方式。这里是一个示例图表，展示了对主页所做的更改：

flowchart LR
  beta>Beta 分支]
  main>Main 分支]

  beta-changes(主页的示例更改)
  latest-changes(主页的不同更改)

  beta-pr([Beta PR 合并])
  latest-pr([Main PR 合并])


  beta-->beta-pr
  beta-changes-->|向 beta 提交更改|beta-pr
  main-->latest-pr
  latest-changes-->|向 main 提交更改|latest-pr

  beta-pr --> |部署 beta 版本| beta-deployment
  latest-pr --> |部署 latest 版本| latest-deployment

  beta-deployment{{Beta 部署}}
  latest-deployment{{Latest 部署}}

你会注意到现在每个版本的首页都不同，特别是 main 分支上的主页已经被添加了 beta 分支版本中不包含的更改。现在，如果看看当 beta 版本作为最新版本发布时会发生什么：

flowchart LR
  beta>Beta 分支]
  main>Main 分支]

  beta-deployment{{Beta 部署}}
  latest-deployment{{Latest 部署}}

  beta --> |部署到 latest| latest-deployment
  beta --> |为下一个 beta 版本创建副本| beta-deployment

  merge([合并 beta 到 main])

  beta --> |用 beta 覆盖 main| merge
  main --> |被 beta 覆盖的更改| merge

  main --> |部署 main 作为其版本号| gh-pages[(旧版本)]

当我们发布 beta¹ 版本时，我们将 latest¹ 版本复制到 old-versions，将其名称更改为其版本号。然后，beta¹ 版本被部署到 latest¹，并为开发下一个版本创建一个副本。最后，beta 分支与 main 分支合并。这意味着 main 分支中添加的任何更改都将被 beta 分支覆盖。

现在，你已经了解了系统的工作原理，你可以看到为什么 main 分支中添加的更改不会包含在文档的未来版本中。

这对应于文档版本选择器中的标签。 ↩↩↩↩↩↩↩↩↩↩↩↩