跳到主要内容

参与维护 Robonix 文档

Robonix 文档与代码共同构成对外接口。命令、目录、配置字段或预期输出写错，会直接阻塞机器人接入；因此文档修改采用与代码相同的责任人审查和持续集成（CI）门槛。

本页只说明如何修改 syswonder/robonix-book。向 Robonix 主仓库提交实现时，请阅读贡献 Robonix 代码。

维护角色​

社区中的任何人都可以报告问题、修改任意页面或参与审查。合并责任按路径分配，避免把所有更新集中到单一维护者。

角色责任不代表什么
贡献者复现问题，提交 issue 或 pull request（PR），提供验证证据不需要先成为仓库成员
文档维护者审查结构、语言、链接、构建和跨页面一致性不替代领域负责人判断技术行为
领域负责人核对所属组件、接口、部署流程或硬件安全要求不拥有相关页面的排他编辑权
发布编辑核对文档版本、对应源码和发布状态不自行批准未经领域审查的技术变更

.github/CODEOWNERS 只用于自动请求合适的审查者。它不限制其他贡献者修改文件，也不赋予原作者永久控制权。普通文档变更至少需要一名非作者审查者批准；下列变更至少需要一名文档维护者和一名相关领域负责人分别批准：

  • 标准能力约定、IDL、软件包或机器人部署清单字段；
  • 安装、构建、启动、升级和兼容性流程；
  • 底盘、机械臂、急停、网络暴露和凭据处理等安全相关说明；
  • 分支政策、发布状态和自动生成参考资料。

维护团队每季度检查一次 CODEOWNERS：移除长期不可用的责任人，为无主目录补充共同维护者，并从持续贡献和审查的社区成员中邀请新维护者。

先选择贡献入口​

直接提交 PR​

以下修改可以直接提交 PR：错别字、失效链接、不会改变行为含义的措辞修正，以及已有实现的明确补充。PR 中仍需指出受影响页面和验证方式。

先提交 issue​

以下情况先在 syswonder/robonix-book issues 说明问题，避免多人重复实现或把尚未确定的设计写成既成事实：

  • 文档与实际命令、接口或运行结果不一致；
  • 需要新增、删除或大幅重组章节；
  • 代码行为尚未进入目标源码分支；
  • 同一修改会影响多个仓库、软件包或机器人部署；
  • 需要决定兼容、弃用或迁移策略。

issue 应包含页面链接、Robonix 源码分支和 commit、操作系统或机器人型号、实际命令、完整错误，以及期望行为。不要只提交截图；可复制的文本日志应放在代码块中。凭据、令牌和个人数据不得进入公开 issue。

提交文档 PR​

  1. 从文档仓库最新 main 创建短期分支。

  2. 只修改解决该问题所需的页面；大规模移动文件和内容改写应拆成不同提交。

  3. 按仓库根目录的 STYLE.md 编写或修改内容。

  4. 逐条执行页面中的新增或变更命令，并记录源码 commit、环境和结果。

  5. 首次贡献时，在仓库根目录安装锁定的 Node.js 依赖：

    make install

  6. 启动可编辑的本地预览：

    make dev

    打开 http://127.0.0.1:3000/。保存 docs/、src/、static/、sidebars.ts 或 docusaurus.config.ts 中的文件后，Docusaurus 会重新编译并刷新预览。

    开发预览中的“最后更新”使用 Docusaurus 的模拟作者和时间，并明确标为模拟值。生产构建才从 Git 提交记录读取真实作者与更新时间；不要根据开发预览中的“模拟作者”或 2018 年的模拟日期判断页面历史。

  7. 在提交前运行完整本地检查：

    make check

    该命令依次检查 Bash、JavaScript、JSON、Python、TOML 和 YAML 代码块语法，检查本地图片路径与替代文本，执行 TypeScript 类型检查，生成 build/ 生产站点，再校验站内链接、旧版 mdBook 页面与锚点以及搜索索引。命令必须以状态码 0 退出。

  8. 检查导航、页内目录、代码块、表格、窄屏布局和所有受影响页面。视觉修改应在拉取请求中附桌面与窄屏截图。

  9. 使用拉取请求模板填写影响范围、验证证据、兼容性和人工智能辅助披露；关联问题，例如 Closes #123。

页面右上角的编辑入口用于创建针对该源文件的修改。无法立即修复时，使用页面上的仓库链接报告问题，并附页面 URL、对应源码版本和复现环境。

可执行内容的证据要求​

文档不得根据记忆补全命令或推测输出。修改者必须从目标分支的实际实现、命令帮助、config.spec、软件包清单、测试或运行日志中取证。

内容PR 中必须提供的证据
CLI 命令或参数目标 commit 上的 --help 或实际执行结果
配置字段解析该字段的源码、config.spec 或已合并的接口定义
目录结构对应 commit 的真实文件树或脚手架生成结果
预期输出同一命令的真实输出；可变值使用有含义的占位符
机器人与软件包接入构建结果、启动日志、能力注册结果及适用硬件
UI 操作当前界面截图和完整点击路径

无法实际验证的内容必须标为“设计提案”或“尚未验证”，不能放入快速上手和接入流程。涉及实机运动时，PR 还应说明急停、限速、架空测试或隔离区域等安全条件。

文档层级与验收标准​

不同页面承担不同任务，审查时不要把架构解释混入操作步骤，也不要在参考页中隐含运行流程。

层级包含内容验收重点
操作指南快速上手、本体接入、软件包开发、部署与排障前置条件、工作目录、每一步动作、预期结果和清理方式均可复现
概念说明组件职责、数据流、能力模型和设计边界术语一致，职责与当前实现相符，并链接到操作指南和接口参考
接口参考能力约定、IDL、字段、命令行接口和生成资料可追溯到对应源码；可生成内容不得手工漂移
项目治理贡献、版本、发布和维护流程责任明确，状态真实，不把计划写成已实现功能

操作指南面向第一次执行任务的读者；概念说明回答“为什么”和“如何协作”；接口参考回答精确名称、类型和约束。同一事实只保留一个权威定义，其他页面通过链接引用。

CI 与预览门槛​

每个拉取请求必须通过仓库设置为必需的检查。当前检查覆盖以下范围：

  • Docusaurus 的 TypeScript 检查和生产构建成功；
  • Bash、JavaScript、JSON、Python、TOML 和 YAML 代码块通过对应语法解析器；
  • 文档图片使用有效的本地资源路径并提供替代文本；
  • 导航配置、站内链接和标题锚点有效；
  • 自动生成的能力约定与 IDL 参考和声明的 Robonix 源码修订号一致；
  • 构建产物作为 PR preview artifact 提供，审查者不必在本地猜测排版结果。

日常编辑使用 make check。修改代码接口页、API 入口或构建流程时，还要用与 ROBONIX_SOURCE_REVISION 一致且无本地修改的 Robonix 源码检出执行完整检查：

make api-install ROBONIX_SOURCE=/absolute/path/to/robonix
make full-check \
  ROBONIX_SOURCE=/absolute/path/to/robonix \
  API_PYTHON=.venv-api/bin/python

拼写、术语和可执行示例仍由提交者与审查者按本页的证据要求核验。后续若增加自动检查，应先在独立 PR 中证明不会因中文正文、命令占位符或硬件相关示例产生系统性误报，再设为 required check。

外部链接容易受网络波动和站点限流影响，适合由定时任务巡检；只有本次修改新增或变更的外部链接应阻塞 PR。合并者不得跳过失败检查；如果检查本身有缺陷，先修复或记录豁免原因和跟踪 issue。

更新自动生成参考​

docs/reference/contracts.md 和 docs/reference/idl.md 不接受手工修改。更新 ROBONIX_SOURCE_REVISION 后，先准备一份当前提交（HEAD）等于该修订、已包含子模块且工作树干净的 Robonix 源码检出，再从手册仓库根目录运行：

make reference ROBONIX_SOURCE=/absolute/path/to/robonix
git diff -- docs/reference/contracts.md docs/reference/idl.md

该目标会验证源码当前提交与 ROBONIX_SOURCE_REVISION 完全相等，拒绝脏工作树，构建固定修订中的 rbnx，在临时目录生成两份 Markdown，经 Docusaurus 归一化后替换参考页。提交前审查完整差异，然后运行 make check。

版本与翻译​

当前站点只发布单一的 current 文档集，且只配置中文 zh-Hans。仓库尚未建立按文档版本保存 ROBONIX_SOURCE_REVISION、生成对应 rustdoc/Sphinx 产物和校验链接的机制，也没有版本切换器。因此版本化是预留能力，不是当前发布流程；不要直接运行 Docusaurus 的 docs:version 命令并把产物当作可维护版本。

启用文档版本前，发布设计必须同时完成：为每个版本固定 Robonix 源码修订；把 API 产物发布到版本专用路径；让基线横幅和参考页读取当前所览版本的修订；在导航中添加 docsVersionDropdown；并在 CI 中检查每个受支持版本的页面、锚点和 API 入口。

翻译也尚未启用。增加新语言前，需要完成正文与界面消息翻译，在 docusaurus.config.ts 登记 locale，添加 localeDropdown，并验证该 locale 的导航、搜索和内部链接。在这些条件齐备之前，不生成 i18n/ 骨架，也不在公开导航中声称支持其他语言。

使用 AI 辅助​

可以使用生成式 AI 查找候选文件、改写文本或生成初稿，但提交者对每一行内容负责。PR 必须披露 AI 是否生成或实质改写了内容，并说明人工完成的源码核对和命令验证。AI 输出不能作为技术正确性的证据，也不能代替领域负责人审查。不得向外部模型提交密钥、未公开代码、用户数据或设备日志中的敏感信息。

写作与审查基准​

本流程借鉴以下成熟社区实践，并按 Robonix 的 GitHub 与机器人实机验证需求进行了调整：