贡献指南

贡献指南#

我们衷心欢迎对项目的贡献，以使框架更加成熟和有用。这些可能以以下形式出现:

  • Bug 报告: 请在 issue tracker 中报告您发现的任何错误。

  • 功能请求: 请在 discussions 中建议您希望看到的新功能。

  • 代码贡献: 请提交一个 pull request 。

    • 错误修复

    • 新功能

    • 文档改进

    • 教程和教程改进

注意

我们更喜欢使用GitHub discussions ，讨论想法，提出问题，交谈和新功能的请求。

请仅使用 issue tracker 跟踪具有明确范围和清晰可交付成果的可执行工作。这些可以是修复错误、新功能或常规更新。

贡献代码#

我们使用 GitHub 进行代码托管。请按以下步骤贡献代码:

  1. 在 issue tracker 中创建一个问题，讨论您想要进行的更改或添加。这有助于我们避免重复工作，并确保更改与项目路线图保持一致。

  2. 分叉存储库。

  3. 为您的更改创建一个新分支。

  4. 进行更改并将其提交。

  5. 将更改推送到您的分叉版本。

  6. 提交一个 到主分支的pull request 。

  7. 确保执行pull请求模板中的所有检查。

发送pull请求后，维护人员将审查您的代码并提供反馈。

请确保您的代码格式良好、有文档并通过所有测试。

小技巧

保持pull请求的尽可能小是很重要的。这样便于维护人员审查您的代码。如果您进行了多个更改，请发送多个pull请求。大型pull请求难以审查，可能需要很长时间才能合并。

编码风格#

我们遵循 Google Style Guides 作为代码库的规范。对于Python代码，遵循PEP指南。最重要的是 PEP-8 用于代码注释和布局， PEP-484 和 PEP-585 用于类型提示。

对于文档，我们采用 Google Style Guide 进行文档注释。我们使用 Sphinx 生成文档。请确保您的代码有良好的文档并遵循这些规定。

循环导入#

在Python中，当两个模块相互导入时，就会发生循环导入，这是一个常见的问题。您可以通过遵循这篇 StackOverflow post 中概述的最佳实践来防止循环导入。

总的来说，避免循环导入是很重要的，因为它们可能导致不可预测的行为。

然而，在我们的代码库中，我们在子包级别遇到循环导入。这种情况是由于我们特定的代码结构引起的。我们将类或函数及其对应的配置对象组织到单独的文件中。这种分离增强了代码的可读性和可维护性。然而，会导致循环导入，因为在许多配置对象中，我们使用属性 class_type 和 func 将类或函数指定为默认值。

为了解决循环导入，我们利用 typing.TYPE_CHECKING 变量。这个特殊变量只在进行类型检查时进行评估，这样我们就可以在配置对象中导入类或函数而不触发循环导入。

重要的是要注意，在我们的代码库中，这是唯一一个使用和接受循环导入的实例。在所有其他情况下，我们遵循最佳实践，建议您也一样做。

类型提示#

为了使代码更易读，我们为所有函数和类使用 类型提示 。这有助于理解代码并使其更易于维护。遵循这种实践也有助于使用静态类型检查器如 mypy 及早捕获错误。

为了避免重复努力，我们在文档中不指定参数和返回值的类型提示。然而，如果您的函数或类不容易理解，请添加带有类型提示的文档注释。

工具#

我们使用以下工具来维护代码质量:

  • pre-commit: 在代码库上运行一系列格式化程序和检查器。

  • black: 无可妥协的代码格式化程序。

  • flake8: PyFlakes、pycodestyle和McCabe复杂性检查器的包装器。

请检查 此处 有关设置的说明。要在整个存储库上运行，请在终端中执行以下命令:

./isaaclab.sh --format  # or "./isaaclab.sh -f"

贡献文档#

贡献文档与贡献代码库一样简单。所有文档的源文件都位于 IsaacLab/docs 目录中。文档是用 reStructuredText 格式编写的。

我们使用 Sphinx 与 Book Theme 来维护文档。

发送文档的pull请求与发送代码库的pull请求相同。请遵循 Contributing Code 部分中提到的步骤。

小心

为了构建文档，我们建议创建一个 虚拟环境 来安装依赖。这也可以是一个 conda环境 。

要构建文档，请在终端中运行以下命令，该命令安装所需的Python包并使用 docs/Makefile 构建文档:

./isaaclab.sh --docs  # or "./isaaclab.sh -d"

文档生成在 docs/_build 目录中。要查看文档，请打开 html 目录中的 index.html 文件。您可以通过在终端中运行以下命令来执行此操作:

xdg-open docs/_build/html/index.html

提示

xdg-open 命令用于在默认浏览器中打开 index.html 文件。如果您使用的是另一个操作系统，可以使用适当的命令在浏览器中打开文件。

要进行干净的构建，请在终端中运行以下命令:

rm -rf docs/_build && ./isaaclab.sh --docs

贡献资产#

当前，我们将扩展的资产托管在 NVIDIA Nucleus 服务器 上。Nucleus 是一个基于云的存储服务，允许用户存储和共享大文件。它与 NVIDIA Omniverse 平台 集成。

由于所有资产都托管在 Nucleus 上，我们不需要在存储库中包含它们。但是，我们需要在文档中包含资产的链接。

包含的资产是 Isaac Sim 内容 的一部分。要使用此内容，您需要将文件下载到 Nucleus 服务器上或在 Nucleus 服务器上创建 Isaac Mount。

请查看 Isaac Sim 文档 了解有关如何下载这些资产的详细信息。

注意

我们目前正在努力寻找更好的贡献资产的方法。一旦我们有解决方案，我们将更新本节。与此同时，请按照以下步骤操作。

托管您自己的资产，当前的解决方案是:

  1. 为资产创建一个单独的存储库，并将其添加到那里

  2. 确保资产具有使用和分发许可

  3. 在存储库的 README 文件中包含资产的图像

  4. 发送一个包含指向存储库的链接的拉取请求

然后，我们将验证资产及其许可证，并将资产包含到 Nucleus 服务器进行托管。如果您有任何问题，请随时通过电子邮件与我们联系，或通过在存储库中开启问题来联系我们。

维护变更日志#

每个扩展在 docs 目录的 CHANGELOG.rst 文件中维护一个变更日志。该文件采用 reStructuredText 格式编写。它包含了每个扩展版本的经过策划和按时间顺序排列的显著变更列表。

此变更日志的目标是帮助用户和贡献者精确查看每个版本或扩展的显著变更。对于每个扩展，这是*必需*的。

为了更新变更日志，请按照以下准则操作:

  • 每个版本应该有一个包含版本号和发布日期的部分。

  • 根据 语义化版本 更新版本号。发布日期是该版本发布的日期。

  • 每个版本根据所做更改的类型进行分段。

    • Added: 新功能。

    • Changed: 现有功能的更改。

    • Removed: 现在删除的功能。

    • Removed: 目前已移除的功能。

    • Fixed: 任何 bug 修复。

  • 将每个更改描述在相应的小节中，使用项目符号。

  • 项目符号使用过去时和命令式。

例如，以下是一个示例变更日志:

Changelog
---------

0.1.0 (2021-02-01)
~~~~~~~~~~~~~~~~~~

Added
^^^^^

* Added a new feature.

Changed
^^^^^^^

* Changed an existing feature.

Deprecated
^^^^^^^^^^

* Deprecated an existing feature.

Removed
^^^^^^^

* Removed an existing feature.

Fixed
^^^^^

* Fixed a bug.

0.0.1 (2021-01-01)
~~~~~~~~~~~~~~~~~~

Added
^^^^^

* Added a new feature.