update-documentation

更新文档

处理 docs.tenzir.com 变更的运维工作流。

工作流

1. 确保 .docs/ 已存在且为最新状态，方法是克隆 tenzir/docs 或 从 origin 获取更新。
2. 在 .docs/ 中创建或检出一个与父仓库分支名称一致的主题分支。
3. 在 .docs/ 中编写内容更新，并遵循文档仓库自身的文档编写指南和 约定。
4. 如果文档仓库提供相关检查，请运行这些检查。
5. 从 .docs/ 提交 tenzir/docs 拉取请求。
6. 使用统一且简洁的页脚格式互相关联拉取请求：
   • 在文档 PR 中，追加一个最终的 <sub>...</sub> 页脚块，链接代码 PR 并引用相同的 Linear 问题，例如 ⚙️ Code PR: tenzir/tenzir#6048<br>🎫 References TNZ-150, TNZ-151。
   • 在代码 PR 中，在最终的 <sub>...</sub> 页脚中追加或扩展 📚 Docs PR: tenzir/docs#261。
   • 两个方向的 PR 链接都使用 GitHub 简写形式，例如 tenzir/tenzir#6048 或 tenzir/docs#261，而不是完整 URL。只有在 简写无法表达深层链接时才使用完整 URL，例如指向特定评论的链接。
   • 优先使用该页脚，而非单独的 Code PR 或 Docs PR 部分。如果已有页脚，请添加另一个以 <br> 分隔的行，而不是新建第二个页脚。
7. 总结变更内容，并注明任何后续工作。

分支管理

尽可能让 .docs/ 分支名称与代码分支保持一致。 如果代码变更涉及多个仓库，请以代码分支作为命名和交叉链接的 依据。

PR 交叉链接格式

在每个 PR 描述末尾使用简洁的页脚，关联文档和代码 PR。在文档 PR 页脚中，用 references 等非关闭 issue 的词语引用相同的 Linear 问题，避免配套的文档 PR 独立推进该 issue。如果多个问题具有相同的关系，请在一行中将它们列在同一个魔法词后，以保持页脚简洁。 只有关系不同时才使用单独的行。

文档 PR 示例：

<sub>
⚙️ Code PR: tenzir/tenzir#1234<br>
🎫 References TNZ-150, TNZ-151
</sub>

代码 PR 示例：

<sub>
📚 Docs PR: tenzir/docs#261<br>
✅ Closes TNZ-150, TNZ-151<br>
📎 Related: tenzir/tenzir#5999
</sub>

交叉检查

打开文档 PR 之前：

1. 确认修改后的页面仍符合其 Diataxis 分类。
2. 检查相邻页面和“另请参阅”链接，确认是否需要后续编辑。
3. 确保代码示例、路径和 UI 标签与当前产品行为一致。