企业官网建设流程全解析

• 文档
• 教程
• 云原生

本文以knative/docs仓库的官方协作流程文档为核心，系统讲解文档贡献者的本地环境配置、Issue 提报规范、Pull Request 的提交与评审机制，以及 Prow 机器人命令（/assign、/lgtm、/approve、/cherrypick等）的用法。读完本文，你将能够独立完成从克隆 fork 仓库到跟踪 PR 通过 CI、获得lgtm与approved双标签自动合并的完整闭环。

一、整体协作模型概览

Knative 文档仓库的协作建立在三个层面之上：

• GitHub fork + PR 流程：贡献者在自己 fork 的仓库中改文档、提 PR，主仓库不直接开放 write 权限；
• OWNERS 审批体系：仓库根目录的 OWNERS 文件定义了谁有资格对 PR 执行/approve，Prow 依据它自动合并满足条件的 PR；
• Prow 命令体系：通过/assign、/lgtm、/approve、/kind、/area等评论命令对 Issue 和 PR 做比 GitHub 原生权限更细粒度的管控——Prow 允许控制特定 GitHub 功能，而无需授予可以改写仓库历史的完整 write 权限。

仓库的 CI 与发布工具链也可在本仓库中直接验证：PR 触发的校验工作流位于 .github/workflows/ 目录，Netlify 站点构建配置在 netlify.toml，多版本站点构建逻辑在 hack/build.sh，Prow 每 PR 执行的测试入口在 test/presubmit-tests.sh。

二、配置本地开发环境

按官方文档要求，贡献者需要完成以下三步：

1. 创建属于你自己的knative/docsfork；
2. 配置通过 SSH 访问 GitHub 的凭证；
3. 将 fork 克隆到本地，并把上游knative/docs仓库配置为upstreamremote：

mkdir -p ${GOPATH}/src/knative.dev cd ${GOPATH}/src/knative.dev git clone git@github.com:${YOUR_GITHUB_USERNAME}/docs.git cd docs git remote add upstream https://github.com/knative/docs.git git remote set-url --push upstream no_push

最后一条命令git remote set-url --push upstream no_push是 Knative 系仓库的标志性做法：它将upstream的推送地址设为一个无效值，从而从本地工具层面杜绝任何人向主仓库直接 push，所有变更必须走 PR 评审流程。完成上述配置后，你就具备了提 PR、参与评审和提交修复的资格。

注意：要定期同步（sync）你的 fork，保持它与上游main分支一致，否则后续提 PR 时容易产生冲突。

三、提交文档 Issue

Knative 用 GitHub Issues 跟踪所有文档类问题与需求。如果你发现文档问题但不确定如何修复，先按以下流程提 Issue：

1. 在knative/docs的 issues 列表中检查是否已有同类问题，避免重复提交；
2. 为新 Issue 选择正确的模板。文档中说明提供两类模板，而当前仓库的 .github/ISSUE_TEMPLATE/ 目录下实际已包含三个模板文件：

提 Bug 报告时建议包含尽可能多的细节和修复建议；如果你知道问题关联哪个 Knative 组件，还可以指派对应的 Working Group Lead。

边界说明：产品行为或代码本身的缺陷应提交到各自的 Knative 组件仓库，而不是本仓库；文档类问题统一提交到knative/docs。

四、提交修复文档的 Pull Request

Knative 文档遵循标准的 GitHub 协作流。完整的提 PR 步骤如下：

1. 确保 fork 已与上游同步到最新；
2. 在 fork 中创建一个新分支；
3. 定位或创建要修改的文件：
   • 更新已有页面时，可以直接在 Knative 网站页面上方点击铅笔图标跳转到对应源文件，也可以在自己的本地克隆中打开该文件；
   • 新增内容时必须遵循"新文档"规范，即使用对应内容模板：Concept、Procedure、Troubleshooting 或 Blog。值得注意的是，向/docs目录添加新文档后导航菜单会自动更新（MkDocs 机制），无需手工维护导航；
4. 使用新分支编辑文件（可通过 GitHub UI 操作，也可以在本地克隆中编辑后 push）；
5. 在knative/docs仓库创建 Pull Request；
6. 为 PR 指定 owner 以请求评审（见下文）。

PR 模板与描述规范

提交 PR 时会预填 PR 模板，其开头要求填写"Fixes #issue-number"或一段描述该 PR 解决问题的说明，并在 "Proposed Changes" 一节概述变更内容。模板注释中还给出两条重要指引：

• 新增文档必须选用四类内容模板之一（Concept / Procedure / Troubleshooting / Blog）；
• 如果变更需要同步到最近的已发布版本，使用 Prow 的/cherrypick命令（例如/cherrypick release-1.2），由 Prow 自动为对应 release 分支生成 PR。

PR 合入前的 CI 校验

从仓库的 GitHub Actions 配置可以确认，一个 PR 在main或release-*分支上会触发以下校验（配置均位于 .github/workflows/ 目录）：

此外，knative-docs-image.yaml 定义了当 PR/push 改动示例代码路径（如code-samples/serving/hello-world/helloworld-go/**、code-samples/eventing/bookstore-sample-app/**）时自动构建并推送示例镜像，这意味着修改示例代码的 PR 会连带触发镜像构建校验。PR 合并后，knative-dot-release-build.yaml 会在release-1.*分支推送时通过 Netlify build hook 触发版本化站点重建。

Prow 侧的测试入口是 test/presubmit-tests.sh，该脚本 source 了 vendored 的knative.dev/hack/presubmit-tests.sh，按默认顺序执行 build、unit、integration 测试，注释明确说明"由 Prow 为每个 PR 启动，也可以手动执行"。

五、PR 评审流程

PR 提交后的典型流转过程如下：

1. 分诊（Triage）：被指派的仓库维护者对 PR 分诊——设定相对优先级、打上相应标签、完成初步文档评审；
2. SME 技术评审：如果 PR 涉及重要的技术变更（例如新功能、新增或修改的示例代码），会被指派给 Subject Matter Expert（通常是参与 Knative 开发的工程师）做技术评审与批准；
3. 双标签合并：当技术写作与 SME 双方都满意后，PR 才允许合并。合并前 PR 必须同时具备lgtm和approved两个标签：
   • lgtm由负责技术准确性的 SME 添加；
   • approved由 Knative 技术写作成员在内容满足质量、清晰度与组织标准后添加（标准参见 Knative 风格指南）。

谁有权 Approve：OWNERS 文件

仓库根目录的 OWNERS 文件即 Prow 判定审批资格的依据，当前配置为：

• approvers：docs-writers、technical-oversight-committee、steering-committee、knative-release-leads、ux-wg-leads，以及 client、eventing、functions、operations、serving 各 working group 的 leads；
• reviewers：docs-writers、docs-reviewers、ux-wg-leads。

这些别名对应的具体成员列表由 OWNERS_ALIASES 维护（该文件由 peribolos 自动同步生成，不应手工修改）。例如docs-writers别名当前映射到skonto，docs-reviewers映射到nainaz、skonto。这解释了为什么"任何人都可以/lgtm一个 PR，但只有列在 OWNERS 文件中的人才能/approve"。

六、指派 Owner 与 Reviewer

规范要求每个 PR 都应指派唯一 owner（即 GitHub 的 Assignee）。最佳做法是手动设置 Assignee、把其他干系人加为 Reviewer，而不是放任 Prow 自动分配评审人。相关 Prow 命令：

• 用/assign设置 owner，例如：/assign @owner_id；
• 用/cc抄送其他干系人参与评审，例如：/cc @stakeholder_id1 @stakeholder_id2。

对涉及代码的变更：初始 owner 应设为负责技术准确性审查的 SME。如果不确定合适的 owner 或 reviewer 是谁，可以指派相关组件的 current working group lead。

七、使用 Prow 管理 PR 与 Issue

Prow 会在大多数 bug 和 PR 上"发声"，并附上已知命令的完整列表。日常最常用的命令如下：

• /assign @user1 @user2：将 Issue 或 PR 指派给特定人员评审或批准；
• /lgtm与/approve：批准 PR。任何人都可以/lgtm，而只有OWNERS文件中列出的 approver 才能/approve；PR 需要二者齐全才会被 Prow 自动提交（auto-submit）。/lgtm是一个让无 approve 权限的参与者练习评审能力的好机会——当 PR 更新后/lgtm会被移除，而/approve具有粘滞性（sticky），即一旦打上，之后任何人对新内容补充/lgtm即可推进合并；
• 测试：Prow（传统）与 GitHub Actions（推荐方式）都可在 PR 上运行测试；所有测试通过且 PR 同时拥有lgtm与approved标签后，Prow 会自动提交该 PR；
• 标签管理：可用/kind ...、/good-first-issue、/area ...为 PR 打分类标签；
• 版本回移：/cherrypick命令的完整用法见 分支与 Cherrypicking。

分支模型与 Cherrypick 的配合

理解 Prow 自动合并还要理解文档的版本分支模型（详见 doc-releases.md 与 branches-and-cherrypicking.md）：main分支是开发中（pre-release）版本，对应官网 Pre-release 菜单；各已发布版本的文档存放于release-#.#分支。默认新内容写在main，需要进入某发布版本时通过/cherrypick release-x.y自动回移。这一点也可以从构建脚本得到印证：hack/build.sh 中的VERSIONS数组维护当前构建的三个已发布版本（当前为1.23、1.22、1.21），并逐一以 git worktree 检出对应release-*分支构建版本化站点。

八、常见问题（FAQ）

官方文档汇总了两类高频问题：

• CLA 检查失败但已签署 CLA：常见原因是你在他人账户的 PR 中接受了其 suggestions 并产生 commit。该账户的邮箱与 CLA 登记邮箱不一致时，commit 会显示为 co-author，若该公开邮箱未签署 CLA 即导致检查失败；
• 部分测试失败：如果没有看到与你改动相关的明确错误，而失败信息是超时（timeout）类，建议在稍后时间重跑测试——同一时间运行的其他任务可能引起超时或触发限流（rate limiting）。

遇到其他问题可以在 CNCF Slack 的#knative-documentation频道求助。

九、延伸阅读

• Knative 文档贡献者指南总入口：涵盖成为贡献者、格式规范、导航与重定向等全部主题；
• 本地预览网站：推荐通过./hack/docker/run.sh在容器中启动 MkDocs 实时预览（hack/mkdocs.sh封装了mkdocs serve --config-file ./mkdocs.yml --livereload）；提交 PR 后也会自动生成 live preview 链接；
• 风格指南：代码文档化、格式约定、语言风格与用词表——官方态度是"尽早提交不完美的贡献，好过迟迟交上完美的贡献"。

• 文档
• 教程
• 云原生