捐赠 爱心图标 GitHub 仓库

提交拉取请求

更改 Bevy

大多数更改不需要太多“流程”。如果您的更改比较简单，只需执行以下操作

  1. 社区成员（就是您！）创建以下内容之一
    • GitHub 讨论：与社区进行非正式讨论。如果您想提出功能或特定实现，这是开始的地方。
    • 问题：我们跟踪错误或功能的正式方式。在打开新问题之前，请查看是否有重复项，并考虑从讨论开始。
    • 拉取请求（简称 PR）：合并代码更改的请求。这开始了我们的“评审流程”。欢迎您从拉取请求开始，但对于较大的更改（或者如果您不确定设计），请考虑从问题或讨论开始。我们不希望任何人浪费时间在没有机会合并的代码上！但另一方面，有时 PR 是提出更改最有效的方式。在这里使用您自己的判断。
  2. 其他社区成员会以随机的方式进行评审和评论。积极的主题专家可以使用 @mentions 被拉入主题。如果您的 PR 已经沉默了一段时间并且准备进行评审，请随时留言“bump”主题，或者在 Discord 的相应引擎开发频道中提出。
  3. 一旦他们对拉取请求（设计、代码质量、文档、测试）感到满意，单个评审人员就会留下“批准”评审。
  4. 达成共识后（有关更多信息，请参阅 评审拉取请求）并且 CI 通过，将添加 S-Ready-For-Final-Review 标签。
  5. 当他们有时间时，项目负责人或维护者将执行最终代码评审并排队 PR 以供合并。

复杂更改

个人贡献者经常领导主要的全新功能和重构。但是，这些更改需要更多设计工作和审查。像这样的复杂更改倾向于经历以下生命周期

  1. 识别需求或机会并创建一个问题，概述一般问题。
  2. 根据需要，在该问题主题、交叉链接的 GitHub 讨论 主题或 Discord 的引擎开发频道中进一步讨论此问题。
  3. 创建草案拉取请求或 RFC。如 RFC 仓库 中所述，复杂的功能需要 RFC，但这些 RFC 可以先于或后于原型工作开始提交。
  4. 如果可行，可以将独立工作的部分（即使它们只有在合并了完整的复杂更改后才有用）拆分为单独的 PR，以使它们更容易评审。
  5. 整个社区帮助改进草案 PR 和/或 RFC，留下评论、提出建议并向原始分支提交拉取请求。
  6. 一旦 RFC 合并或草案拉取请求从草案模式过渡，上一节中概述的正常更改流程 就可以开始。

贡献代码

Bevy 积极地开放社区成员的代码贡献。如果您是 Bevy 的新手，以下是我们使用的流程

  1. 在 GitHub 上为 bevyengine/bevy 仓库创建分支。如果您还没有 GitHub 帐户，则需要创建一个。

    1. 将 .cargo/config_fast_builds.toml 复制到 .cargo/config.toml。然后更新文件并遵循一般建议 使用性能优化进行编译。

  2. 在本地克隆的分支中进行更改，通常在自己的新分支中。

    1. 尝试将您的工作拆分为单独的提交，每个提交都有一个明确的目的。在响应评审时尤其要注意这一点，这样可以很容易地看到发生了哪些更改。

  3. 要在本地测试 CI 验证，请运行 cargo run -p ci 命令。这将运行 CI 中发生的大多数检查，但可能需要一些时间。您也可以根据您正在贡献的内容运行子命令以更快地迭代

    • cargo run -p ci -- lints - 运行格式化和 Clippy。
    • cargo run -p ci -- test - 运行测试。
    • cargo run -p ci -- doc - 运行文档测试和文档检查。
    • cargo run -p ci -- compile - 检查所有必须编译的内容仍然可以编译（示例和基准），以及我们希望确保不能编译的内容（crates/bevy_ecs/compile_fail）。
    • 要获取有关可用命令和运行内容的更多信息，请查看 tools/ci 箱。

  4. 使用 Markdown（.md）文件时，Bevy 的 CI 将使用 markdownlint 检查 Markdown 文件（如本文件）。要在本地使用与我们的 CI 相同的工作流程对您的文件进行 lint

    1. 安装 markdownlint-cli。
    2. 在 Bevy 项目的根目录中运行 markdownlint -f -c .github/linters/.markdown-lint.yml .。

  5. 使用 TOML（.toml）文件时，Bevy 的 CI 将使用 taplo 检查其样式和正确性：taplo fmt --check --diff

    1. 如果您使用 VSCode，请安装 Even Better TOML 并格式化您的文件。
    2. 如果您想使用 CLI 工具，请安装 taplo-cli 并运行 taplo fmt --check --diff 以检查格式。通过在 Bevy 项目的根目录中运行 taplo fmt 来修复任何问题。

  6. 检查是否有错别字。Bevy 的 CI 将使用 typos 检查错别字。

    1. 如果您使用 VSCode，请安装 Typos Spell Checker。
    2. 您也可以通过安装 typos-cli 并运行 typos 来检查错别字，并通过运行 typos -w 来修复它们，从而使用 CLI 工具。

  7. 将您的更改推送到您在 GitHub 上的分支并打开拉取请求。

  8. 响应任何 CI 故障或评审反馈。虽然必须修复 CI 故障才能合并您的 PR，但您不必同意评审中的所有反馈，只需确认已收到反馈即可。如果您无法达成一致，请保持主题打开并服从维护者或项目负责人的最终判断。

  9. 当您的 PR 准备合并时，维护者或项目负责人将对其进行评审并建议最终更改。如果这些更改很小，他们甚至可以直接应用它们以加快合并速度。

如果您最终将新的官方 Bevy 箱添加到 bevy 仓库中

  1. 将新箱添加到 tools/publish.sh 文件中。
  2. 检查是否添加了新的 cargo 功能，根据需要更新 docs/cargo_features.md。

贡献时，请

  • 优先考虑小的 PR，这些 PR 可以逐步改进。
  • 解释您在做什么以及为什么这样做。
  • 尝试松散地遵循 更改 Bevy 中的工作流程。
  • 参考 样式指南 来帮助保持我们的代码库整洁。
  • 使用文档注释记录新代码。
  • 包含清晰简单的测试。
  • 在添加新的面向用户的功能时添加或改进示例。
  • 将工作分解成易于消化的部分。
  • 请求您需要的任何帮助！

您的第一个 PR 将很快合并！

无论您如何提供帮助，感谢您为 Bevy 做出的贡献！

样式指南

一般指南

  1. 优先考虑使用细粒度的导入，而不是像 bevy_ecs::prelude::* 这样的全局导入。
  2. 使用一致的注释样式
    1. /// 文档注释应位于 #[derive(Trait)] 调用之上。
    2. // 注释通常应位于相关行之上，而不是内联。
    3. 避免使用 /* */ 块注释，即使是在编写长注释时也是如此。
    4. 在注释中使用 variable_name 代码块来表示您正在引用特定类型和变量。
    5. 以大写字母开头注释。如果它们是句子式的，请在末尾加点。
  3. 使用注释来组织无法合理地重构为单独函数的冗长且复杂的代码段。
  4. 使用 Bevy 错误代码 时，在返回的错误消息 ... See: https://bevy.rust-lang.net.cn/learn/errors/b0003 中包含指向 Bevy 网站上相关错误的链接。

Rust API 指南

作为 API 开发的参考，我们使用 Rust API 指南。通常情况下，应遵循这些指南，但以下几个方面我们不赞同

不一致之处

在 Rust API 指南 中提到的某些方面我们并不赞同。这些方面将在我们发现其他不赞同的地方进行扩展，因此请确保定期查看它们。

所有项目都有 rustdoc 示例

  • 此指南过于严格，并不适用于 Bevy 游戏引擎中的所有内容。对于需要更多上下文或需要更具交互性的演示（例如渲染或输入功能）的功能，请改用 examples 文件夹。

示例使用 ?，而不是 try!，也不是 unwrap

  • 此指南通常是合理的，但并非始终要求。

只有智能指针实现 Deref 和 DerefMut

  • 通常这是一个很好的经验法则，但我们可能会故意违反它来使用单元素包装类型，例如 Life(u32)。行为仍然是可预测的，并且它显着提高了人体工程学/新用户的理解。

接收和回复评审

一旦您创建了 Pull Request (PR)，您的下一步任务就是引导它通过社区审核，以便最终合并。理想情况下，社区成员应该很快就会审核您的工作，但有时 PR 会被遗漏。如果您的 PR 已经存在了几周，但没有人关注，请不要犹豫，在 Discord 上请求审核。

您可能会发现，您的审阅者有时会误解您的工作，要求您进行您不同意的更改，或者要求您进行您不想进行的额外更改。如果您发现自己不同意审阅者，可以礼貌地说“不”，或者表明他们的建议最好留待后续 PR 进行。

采用拉取请求

有时，Pull Request 的作者会变得忙碌或失去响应，或者项目成员未能及时回复。这是任何开源项目中自然的一部分。为了避免阻碍这些工作，这些 Pull Request 可以被“接管”，即另一个贡献者创建具有相同内容的新 Pull Request。如果有一个没有更新的旧 Pull Request，请评论组织是否适合添加“S-Adopt-Me”标签，以表明它可以被“接管”。“S-Adopt-Me”的 PR 应该被关闭，并使用相同的标签打开一个跟踪问题来跟踪它们的接管。

如果您打算自己接管一个 PR，请在跟踪问题中说明。对于尚未标记为开放接管的 PR，您也可以在 PR 上留下评论，询问作者是否计划返回。如果作者同意或在几天后没有回复，那么就可以接管它。由于此时 PR 已经被您接管，因此有时甚至可以跳过标签过程。

添加了这个标签后，最佳实践是派生原始作者的分支。这确保他们仍然因为工作而获得认可，并且保留了提交历史。当新的 Pull Request 准备就绪时，它应该在描述中引用原始 PR。然后，通知组织成员关闭原始 PR。

  • 例如，您可以通过在您的 PR 描述中添加以下内容来引用原始 PR：Adopted #number-original-pull-request

帮助 PR 准备就绪

在不完全接管 PR 的情况下，有时作者需要帮助才能获得批准或通过 CI。这些 PR 可以被标记为“S-Needs-Help”，并且欢迎在它们上打开 PR 来修复最后几个点，解决冲突以通过 CI。您需要与原始作者或维护者之一密切合作，将您的提交添加到原始 PR 中。

改善此页面