Version:

Icon of a magnifying glass.
  在GitHub上编辑

本文内容

Docs 贡献流程概述

任何人都可以成为 Open 3D Engine （O3DE） 文档的贡献者，并确定自己的参与级别。在这里，我们将帮助您完成文档流程，以便您决定如何做出贡献。

在你做任何事情之前

熟悉 O3DE 文档并了解其样式非常重要。花点时间浏览 O3DE 文档。该文档由以下几个指南组成：

  • 欢迎: O3DE 的友好介绍和概述。本指南的目的是让新用户，特别是那些没有太多经验的用户，熟悉 O3DE。如果你有简化技术概念的天赋，那么这是一个很好的研究贡献的领域。
  • 教程和示例: 帮助用户学习 O3DE 的指导教程、示例和说明书。如果您是 O3DE 用户，则提交说明书的配方是无需投入太多时间即可贡献新文档的好方法。
  • 用户指南: O3DE 提供的各种编辑器、工具、组件和 Gem 的功能和参考文档。功能参考很深入，我们有时会错过对 O3DE 的重要功能和更精细细节的报道。对用户指南的贡献始终是必需的，并且非常感谢。
  • Atom Renderer: Atom Renderer 及其工具和编辑器的功能和参考文档。
  • 工具 UI 开发人员指南: O3DE 和 Atom Renderer 工具中使用的 UI 的样式和实现指南。
  • API 参考: 自动生成的 O3DE API 参考。
  • 贡献: 您在这里。为 O3DE 及其文档做出贡献的指南。
  • 发布日志: O3DE 的发行说明，包括新功能、修复和已知问题。

一些文档（如 API 参考）是自动生成的。一些文档，例如 发行说明，由 O3DE SIG 和治理维护和提供。

注意:
以贡献者身份参与需要 GitHub 帐户 。

不想阅读令人厌烦的文字，而更喜欢一个活泼的视频来帮助您入门？请观看此视频！

技术信息

o3de.org 站点使用 Hugo 静态站点生成器 。O3DE 的文档使用 Goldmark ,，这是一种符合 CommonMark 标准的 Markdown 处理器。为 O3DE 文档做出贡献简单、快速，并且不需要任何 Web 开发经验。文档源文件易于阅读，并且需要很少的 markdown 元素。有关设置环境以便您可以为 O3DE 文档做出贡献的信息，请参阅 设置本地 o3de.org 存储库。

从问题开始

创建 GitHub 帐户后，您的第一站应该是当前的 O3DE 文档问题。参见 O3DE repository good-first-issues 。请注意，页面顶部的搜索字段指定了标记为 good-first-issue 的问题。这些问题已被确定为新贡献者的良好切入点。

问题不仅仅是在文档中发现的 bug 和错误。所有贡献（包括新功能文档、教程、配方、站点维护和站点改进）都在问题中跟踪。有关问题的更多信息，请参阅 处理问题。

继续执行拉取请求

熟悉问题后，请查看当前的 O3DE 存储库拉取请求 （PRs） 。PR 是已提交到主存储库的贡献。

开放 PR 目前正由贡献者对几个潜在问题进行同行评审：

  • 技术精度
  • 拼写
  • 语法
  • 清晰
  • 风格

以下是您应该牢记的有关 O3DE 中的 PR 的一些重要准则：

  • 贡献者 不要 合并他们自己的 PR。
  • 每个 PR 在合并到 main 之前必须至少得到贡献者以外的其他人的 两次 批准。
  • 在创建新的 PR 列表之前，请检查打开的 PR 列表。浏览打开的 PR 列表可以让你了解当前活动的主题是什么，并告诉你如何审查不同类型的内容。查看当前的 PR 是个好主意，即使你没有被要求成为审阅者。

文档流程概述

现在你已经熟悉了 O3DE 文档，并且已经对问题和 PR 有了一些了解，让我们看一下为文档做出贡献的高级流程。

  1. 同意 O3DE 贡献者许可协议 （CLA）: 有关详细信息，请参阅项目的 CONTRIBUTING.md 。

  2. 创建新问题或声明现有问题：所有贡献都以 GitHub 问题开头。您可以提交问题，然后将其分配给自己，也可以声明现有问题。创建新问题时，请搜索当前问题列表以确保尚未提交问题。

    在问题分类期间，其他社区成员可能会要求您提供更多信息，而响应是确保您的问题保持相关性的最佳方式。作为贡献者为自己声明 issue 时，请尽量注意其他贡献者正在处理的 PR 和 issue，以确保您的贡献是支持和协作的。就您的问题进行沟通。随着工作的进展留下评论，并回复对问题的评论，在创建拉取请求时将讨论移至拉取请求。有关详细信息，请参阅 处理问题。

  3. **在问题分支上创建分支：**贡献不能直接提交到主 O3DE 文档存储库。您必须复刻主存储库，并从复刻/分支向主存储库提交拉取请求。

    这是一个很好的做法，对于可能审查你的 PR 的贡献者来说，在你的 fork 上为每个新问题创建一个新分支非常有帮助。拥有仅包含问题所需更改的小分支可以加快 PR 审核过程，并有助于与其他贡献者合作。对于大型问题，请考虑将工作分解为较小的问题，并为每个较小的问题创建新的分支。分支中的更改数量越少，就越容易查看和合并到 main 中。有关创建 fork 和分支的更多信息，请参阅 开始为 Doc 做贡献。

  4. 进行更改： O3DE 文档以 CommonMark Markdown 编写，并使用 Goldmark 处理。我们建议在写作过程中使用具有强大 Markdown 支持的编辑器，以便您可以获得实时预览并捕获任何 linting 错误。在写作过程中，请遵循我们的 风格指南 来帮助您的审阅顺利快速地进行。

  5. 提交更改：在提交 PR 之前，必须提交更改并将其推送到 o3de.org 分支上的分支。请确保执行以下操作：

    1. 在提交之前，请确保你的 branch 是最新的 o3de.org/main 。

    2. 签署您提交的更改。签核是 开发者原产地证书 （DCO） 。DCO 是您的证明，证明您的贡献是您自己的原创作品，或者您有权提交该作品。有关提交更改的更多信息，请参阅开始为 Docs 做贡献中的 编写过程 部分。

      重要:
      您必须注销所有提交。当使用git commit提交更改时，使用-s选项来注销。在 GitHub PR 界面中提交单个建议和批量建议时，请在提交建议之前将您的签名(Signed-off-by: Your Name <yourname@yourdomain.com>)粘贴到评论字段中。

  6. 提交拉取请求：将更改提交到自己的分支/分支后，您可以创建对 o3de.org/main 的拉取请求。提交拉取请求时，请确保满足以下条件：

    1. PR 仅包含您希望为 PR 审核的提交和更改。

    2. 如果 PR 有相关问题，则 issue 号必须包含在 PR 标题中。

    3. PR 消息简要而清晰地解释了您提交的更改。

    4. 您已请求至少两个审阅者。合并 PR 需要两名审阅者的批准 - 如果您的贡献具有很深的技术性，则还需要 O3DE 代码贡献者的第三次审阅以确保准确性。你的 PR 上的审阅者越多，你就越有可能越早被签字 - 但未经 D&C SIG 事先批准，切勿请求超过五个审阅者（最多 3 名编辑，最多 2 名技术）。

    5. 如果需要，PR 包含相应的 Labels。标签可以更轻松地对 PR 列表进行排序，并且可以指定 PR 是否正在进行中，寻求反馈和审查，不应合并到o3de.org/main 中。有关更多信息，请参阅 提交文档。

  7. 回复 PR 反馈： 反馈将以评论和建议的形式出现，可以从 GitHub PR 界面提交。重要的是要了解 PR 过程是一个协作讨论。每条评论都不需要处理，每个建议都不需要整合。当贡献者和两个审阅者批准该贡献时，可以集成该贡献。以下是处理建议和评论的一些提示：

    1. 要提交多个建议，请使用批处理功能将多个建议集成到单个提交中。

    2. 在处理评论时，在 PR 中保持相对对话，根据需要编辑主题，并将更改提交到你的 fork/分支。你的新提交将自动添加到 PR 中。

    3. 如果需要，请务必请求重新审核您的新提交。

  8. PR 被合并并关闭： 当意见和建议得到处理，并且两名审阅者批准了 PR 时，它可以合并到 o3de.org/main。永远不要 合并你自己的 PR，最终签字的审阅者负责合并。PR 在合并时自动关闭。

  9. 相关 issue 已关闭：如果你在 PR 的标题中包含了相关 issue 编号，则相关 issue 将在 PR 关闭时自动关闭。您的贡献已完成。恭喜！