文档教程云原生【免费下载链接】docsUser documentation for Knative components.项目地址https://gitcode.com/gh_mirrors/docs1/docs点击查看免费下载本文以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 执行/approveProw 依据它自动合并满足条件的 PRProw 命令体系通过/assign、/lgtm、/approve、/kind、/area等评论命令对 Issue 和 PR 做比 GitHub 原生权限更细粒度的管控——Prow 允许控制特定 GitHub 功能而无需授予可以改写仓库历史的完整 write 权限。仓库的 CI 与发布工具链也可在本仓库中直接验证PR 触发的校验工作流位于 .github/workflows/ 目录Netlify 站点构建配置在 netlify.toml多版本站点构建逻辑在 hack/build.shProw 每 PR 执行的测试入口在 test/presubmit-tests.sh。二、配置本地开发环境按官方文档要求贡献者需要完成以下三步创建属于你自己的knative/docsfork配置通过 SSH 访问 GitHub 的凭证将 fork 克隆到本地并把上游knative/docs仓库配置为upstreamremotemkdir -p ${GOPATH}/src/knative.dev cd ${GOPATH}/src/knative.dev git clone gitgithub.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 时容易产生冲突。三、提交文档 IssueKnative 用 GitHub Issues 跟踪所有文档类问题与需求。如果你发现文档问题但不确定如何修复先按以下流程提 Issue在knative/docs的 issues 列表中检查是否已有同类问题避免重复提交为新 Issue 选择正确的模板。文档中说明提供两类模板而当前仓库的 .github/ISSUE_TEMPLATE/ 目录下实际已包含三个模板文件模板用途要点bug-in-existing-docs.md报告现有文档错误含示例失效、错别字等默认打kind/bug标签模板要求填写 Expected Behavior、Actual Behavior、Steps to Reproduce 及安装信息平台、Knative 版本并附建议的修复方案docs-feature-request.md对未来文档变更或主题增补的需求说明期望看到的变更与补充上下文new-changing-functionality-in-knative.mdKnative 出现新功能或既有功能变化时的文档同步说明变化内容、对用户的影面、预计落地版本并关联其他仓库的相关 PR/Issue提 Bug 报告时建议包含尽可能多的细节和修复建议如果你知道问题关联哪个 Knative 组件还可以指派对应的 Working Group Lead。边界说明产品行为或代码本身的缺陷应提交到各自的 Knative 组件仓库而不是本仓库文档类问题统一提交到knative/docs。四、提交修复文档的 Pull RequestKnative 文档遵循标准的 GitHub 协作流。完整的提 PR 步骤如下确保 fork 已与上游同步到最新在 fork 中创建一个新分支定位或创建要修改的文件更新已有页面时可以直接在 Knative 网站页面上方点击铅笔图标跳转到对应源文件也可以在自己的本地克隆中打开该文件新增内容时必须遵循新文档规范即使用对应内容模板Concept、Procedure、Troubleshooting 或 Blog。值得注意的是向/docs目录添加新文档后导航菜单会自动更新MkDocs 机制无需手工维护导航使用新分支编辑文件可通过 GitHub UI 操作也可以在本地克隆中编辑后 push在knative/docs仓库创建 Pull Request为 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-verify.yaml复用 Knative 统一的代码生成校验verify codegenknative-style.yaml复用统一的代码风格检查stylemkdocs-strict-verify.yaml安装 requirements.txt 中的依赖后执行./hack/build.sh --strict以 strict 模式构建 MkDocs 站点链接失效等问题会在此暴露knative-go-build.yaml / knative-go-test.yaml构建并测试仓库中的 Go 代码如 tools/redir-gen 等工具此外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 提交后的典型流转过程如下分诊Triage被指派的仓库维护者对 PR 分诊——设定相对优先级、打上相应标签、完成初步文档评审SME 技术评审如果 PR 涉及重要的技术变更例如新功能、新增或修改的示例代码会被指派给 Subject Matter Expert通常是参与 Knative 开发的工程师做技术评审与批准双标签合并当技术写作与 SME 双方都满意后PR 才允许合并。合并前 PR 必须同时具备lgtm和approved两个标签lgtm由负责技术准确性的 SME 添加approved由 Knative 技术写作成员在内容满足质量、清晰度与组织标准后添加标准参见 Knative 风格指南。谁有权 ApproveOWNERS 文件仓库根目录的 OWNERS 文件即 Prow 判定审批资格的依据当前配置为approversdocs-writers、technical-oversight-committee、steering-committee、knative-release-leads、ux-wg-leads以及 client、eventing、functions、operations、serving 各 working group 的 leadsreviewersdocs-writers、docs-reviewers、ux-wg-leads。这些别名对应的具体成员列表由 OWNERS_ALIASES 维护该文件由 peribolos 自动同步生成不应手工修改。例如docs-writers别名当前映射到skontodocs-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 与 IssueProw 会在大多数 bug 和 PR 上发声并附上已知命令的完整列表。日常最常用的命令如下/assign user1 user2将 Issue 或 PR 指派给特定人员评审或批准/lgtm与/approve批准 PR。任何人都可以/lgtm而只有OWNERS文件中列出的 approver 才能/approvePR 需要二者齐全才会被 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.mdmain分支是开发中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 链接风格指南代码文档化、格式约定、语言风格与用词表——官方态度是尽早提交不完美的贡献好过迟迟交上完美的贡献。赞分享文档教程云原生【免费下载链接】docsUser documentation for Knative components.项目地址https://gitcode.com/gh_mirrors/docs1/docs点击查看免费下载相关推荐炉石传说 HsMod 插件指南3 步装完变速、开包、换皮肤全都有炉石传说 HsMod 插件指南3 步装完变速、开包、换皮肤全都有 开包开到手酸、过场动画磨人、界面千篇一律炉石传说插件 HsMod 一次接住这三件事它是AI AgentAgent 工作流开发工具MMCV 贡献指南从 Fork 仓库到合入 PR 的完整开发工作流MMCV 贡献指南从 Fork 仓库到合入 PR 的完整开发工作流 本指南面向希望为 OpenMMLab 计算机视觉基础库 MMCV 贡献代码的开发者完整梳人工智能计算机视觉深度学习从Fork到PR合并Ant Design贡献者的完整工作流指南从Fork到PR合并Ant Design贡献者的完整工作流指南 Ant Design作为企业级UI设计语言和React UI库拥有活跃的开源社区。本文将为你UI组件前端设计系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考