跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

贡献

最后更新 查看 MarkdownAgent 设置

Cloudflare Docs 是开源的,托管在 GitHub 上的 cloudflare-docs 仓库 ↗。这意味着任何人,包括非 Cloudflare 组织的成员,都可以对文档做出贡献。我们欢迎所有有助于保持文档高质量和最新状态的建议。

要对我们的文档做出贡献,您需要在 GitHub 上创建一个账户 ↗(如果您还没有的话)并登录。然后您有以下三个选择:

除了使用 Cloudflare 风格指南 获取语法和风格指导外,我们还建议浏览我们的组件,以添加按钮、标签页和可折叠部分等其他格式。

创建 GitHub issue

要创建 GitHub issue:

  1. 登录 GitHub ↗ 并前往 cloudflare-docs 仓库 ↗。
  2. 选择 Issues,然后选择 New issue。
  3. 选择 issue 类型,填写表单,然后选择 Create。

了解有关创建 GitHub issue 的更多信息。 ↗

快速编辑

要使用编辑按钮快速创建 pull request:

  1. 登录 GitHub ↗。

  2. 前往 Cloudflare Docs 中您要编辑的页面

  3. 选择

    Edit 或 Edit page

    Cloudflare Docs 中的每个页面(包括此页面)在右侧边栏都有一个 Edit 按钮,在页面最底部有一个 Edit page 按钮。 编辑图标
    页面的 Markdown 将会打开。

  4. 进行编辑并选择 Commit changes。

  5. 在表单中,更新 Commit message,在方括号中注明您更改的产品,并简要描述您的更改。例如 “[Images] Fixed broken link."

  6. 更新 Extended description,提供有关您更改了什么以及原因的更多详细信息。细节越详细越好。

  7. 依次选择 Propose changes > Create pull request > 再次选择 Create pull request。

完整开发

要通过完整开发工作流 ↗进行编辑并创建 pull request:

  1. 登录 GitHub ↗ 并 fork cloudflare-docs 仓库 ↗。

  2. 如果您在 Web 浏览器中编辑(使用 Codespaces ↗),请转到步骤 3。


    如果您在本地计算机上编辑(使用 Visual Studio Code ↗):

  3. 从您的 fork(或克隆)创建一个分支。

  4. 进行编辑。

  5. 通过安装依赖并启动本地开发服务器来预览您的编辑:

    pnpm install
    pnpm run dev

    终端中会出现一个链接,例如 https://localhost:1111/,您可以在此处预览更改。预览会随着您的编辑自动更新。

  6. 提交您的更改。

  7. 将您的 commit 推送到您的分支,然后推送到您的 fork。

  8. 返回 GitHub 并根据您提交的更改创建 pull request。在描述表单中,在方括号中加入您更改的产品,并简要描述您的更改。例如,“[Images] Fixed broken link.”

创建 issue 或 PR 后

在您创建 issue 或 PR 后,Cloudflare 组织的成员将审核您的建议。以下是后续流程:

  • Cloudflare 组织的成员可能会标记其他人进行技术或内容审核,或者提供反馈。
  • 如果您的建议需要更多信息,Cloudflare 组织的成员可能会通过评论提出后续或澄清问题。如果他们添加了 more-information-needed 标签,且您在 14 天内未做出回应,该 issue 或 pull request 将自动关闭。
  • 如果您的更改被批准:
    • 对于 GitHub issue,Cloudflare 成员可能会创建并链接一个解决您请求的新 pull request。当他们合并 PR 时,也将关闭您的 issue。
    • 对于 GitHub PR,Cloudflare 成员将合并您的 PR。
  • 如果您的建议未被批准,Cloudflare 成员将说明原因并关闭您的 issue 或 PR。

感谢您为我们的开源生态系统做出贡献,并成为 Cloudflare 社区的一员。

内容审核

我们在 GitHub ↗ 中工作(也很乐意这样做),但它绝不是完美的工具。

我们添加了若干易用性改进,以帮助分诊收到的工作、简化审核,并自动沟通。

分诊工作

为帮助作者分诊工作(并辅助后台报告),我们会自动添加若干标签,并分配 issue / pull request。

Pull request

对于 pull request,我们使用特定的 GitHub action ↗ 来添加标签并分配 codeowners。

  • Label products ↗:我们会为顶级产品文件夹添加标签,帮助作者扫视收到的 pull request,并判断哪些与自己相关。
  • Label size ↗:我们会为 pull request 的规模添加标签,帮助作者了解差异的相对大小。这不是完美的度量,但我们会用变更行数来估算 pull request 的规模:
  • Assign codeowners ↗:我们使用 CODEOWNERS ↗ 文件,根据变更的文件自动把人分配到 pull request。这种分配帮助作者筛选并找出与自己相关的 pull request。

Issue

对于 issue,我们使用类似的 GitHub action ↗ 来添加标签并分配 codeowners。

我们的脚本 ↗会单独处理 issue,因为它们通常包含指向站点的链接,而不是仓库内的文件。我们会提取 issue 描述字段中的相关链接,然后据此分配作者(同样基于 CODEOWNERS)并添加产品标签。

简化审核

为简化审核,我们使用若干自动化来帮助解决常见的审核问题。

这会破坏什么吗?

每次 commit 都会运行一项必需检查:CI ↗。

该检查会确保:

谁需要批准?

我们经常收到关于批准的问题,尤其是触及多个产品领域(或我们的组件)的 pull request。

对于打开的 pull request,Cloudflare Docs Bot 会发布一条 Review coverage ↗ 评论,说明哪些区域仍需 CODEOWNERS 批准、建议这些区域的联系人,并汇总已经覆盖的区域。展开 CODEOWNERS mappings 部分,可查看评论中显示的所有权区域对应的精确模式和所有者。该 bot 会跳过草稿、已关闭以及 spam/off-topic 的 pull request。

改了什么?

我们使用一个 GitHub action ↗,为 pull request 上的每次 commit 发布预览构建(并在 pull request 上评论这些链接 ↗)。此操作确保审核者能够看到站点和内容渲染后的实际效果(而不仅仅是在 GitHub 中查看变更的 Markdown)。

我们正在迁移到 Workers Builds,它原生提供该功能。

根据反馈,我们还添加了 before/after 链接表,帮助审核者在预览构建中轻松找到链接。

Before/after 表格

还有什么需要检查?

当 pull request 重命名或删除内容文件路径时,潜在重定向很难检查。

我们有一个专门的 action ↗,会发布评论,帮助审核者识别并检查这些路径。

GitHub Actions 重定向评论

自动沟通

我们主要通过 no-response ↗ GitHub Action 自动沟通。

开源意味着我们接受任何人提交的 issue 和 pull request。其中很多要么不言自明,要么有足够的上下文供我们跟进。

但那些上下文不足的 issue 往往很痛苦(尤其是在我们这样繁忙的仓库 ↗中)。作者必须询问更多细节,然后记得回头查看,有时还要再次追问,然后再检查一次。

为减少这类心理负担,我们会提出问题,然后应用 more-information-needed 标签。该标签会启动一个 14 天倒计时 ↗,等待作者回复。如果他们回复了,标签会被移除,对话可以继续。如果他们没有回复,issue 会自动关闭,并附带一条解释原因的评论 ↗。

无回复评论

我们希望这个工作流能在团队需求与对贡献者的尊重之间取得平衡。

过期 issue

我们有意避免使用会在一段时间无活动后关闭 pull request 或 issue 的 stale 工作流 ↗。

在我们看来,这个工作流带来的摩擦和挫败多于它解决的问题。某件事存在了一年,并不意味着它不再相关。

使用 AI 为 Cloudflare 文档做出贡献

cloudflare-docs 仓库包含一个 AGENTS.md ↗ 文件,它能帮助 AI 编码代理(coding agent)理解仓库的结构、工具和约定,以便他们在为文档做出贡献时进行正确且可构建的更改。

AGENTS.md ↗ 是一种用于引导编码代理的简单、开放的格式。

该仓库开箱即用地包含了以下 AI 工具的配置:

Agent 的技能、命令和 agent 定义都保存在 .agents/ 中,并会自动符号链接到每个工具的预期位置。

这篇文档对您有帮助吗?