MatrixOne 文档贡献指南

欢迎修正文档、补充示例或撰写新指南。中英文源码现在都在同一个 matrixone-doc 仓库。修改页面时请遵守行为守则,并使用 Markdown 与 MyST 语法。

确定页面和目标分支

  • 英文页面位于 docs/en/,中文页面位于 docs/zh/;产品文档在各语言的 MatrixOne/ 目录中。如果改动同时适用于两种语言,请同步检查对应页面与导航。

  • main 对应 latest 文档。历史版本使用独立分支,修改 main 不会自动更新历史版本。先确定受影响版本,再选择 PR 的目标分支。

  • 修改现有页面时使用其源码路径;新增页面时更新同语言相关导航(toctree)。不要把生成的 HTML 当作长期维护的源码。

小修正可使用页面上的 Edit this page 按钮,或提交文档 Issue。中英文改动均通过 matrixone-doc PR 审查。

贡献流程

  1. Fork matrixone-doc,克隆自己的 fork,并添加上游仓库。

    git clone git@github.com:<yourname>/matrixone-doc.git
    cd matrixone-doc
    git remote add upstream https://github.com/matrixorigin/matrixone-doc.git
    
  2. 获取目标分支并从该分支创建工作分支。以最新文档为例:

    git fetch upstream main
    git switch -c docs/my-change upstream/main
    
  3. 修改相应的 Markdown 页面。新增页面时更新同语言 toctree;同时检查链接、代码示例及另一语言的对应页面。

  4. 进行针对性检查。本站使用 Sphinx、Furo 和 MyST,Python 环境由 uv 管理。修改 main 内容时,通常可以运行:

    uv sync
    make html-version VERSION=latest
    git diff --check
    

    对历史版本请使用其配置的版本名。小范围内容修改不必重建所有版本,也不要提交 build/ 或生成产物。

  5. 提交并推送工作分支,不要强推覆盖 main。向负责该版本的分支提出 PR,并说明改动、涉及语言和版本,以及验证结果。

    git add -p
    git commit -m "docs: describe my change"
    git push -u origin docs/my-change
    

网站发布与源码合并是不同步骤。PR 合并不等于所有已部署版本都已重建;部署后还应核对目标版本的页面。

投稿博文

如果有文章或选题构思,可以提交 Issue与社区讨论。