如何为 🤗 LeRobot 做贡献？

我们欢迎任何人做出贡献，并重视每一位贡献者的付出。因此，代码不是帮助社区的唯一方式。回答问题、帮助他人、联系外界以及改进文档对社区来说都非常有价值。

如果你能帮忙宣传，对我们也会有帮助：在博客文章中引用这个库，介绍它所实现的精彩项目；在 Twitter 上分享它对你的帮助；或者简单地给仓库点个 ⭐️ 来表示“谢谢”。

无论您选择何种方式做出贡献，请务必遵守我们的行为准则。

您可以通过多种方式做出贡献！

您可以为 🤗 LeRobot 做出贡献的一些方式

修复现有代码中悬而未决的问题。
实现新的模型、数据集或模拟环境。
为示例或文档做出贡献。
提交与 bug 或期望的新功能相关的问题。

请遵循以下指南，随时提出问题和 PR，并在我们的 Discord 频道上与社区协调您的工作。如有具体问题，请联系 Remi Cadene。

如果您不确定如何贡献，或者想了解我们正在开发的下一个功能，请查看此项目页面：LeRobot 待办事项

提交新问题或功能请求

在提交问题或功能请求时，请尽力遵循这些指南。这将使我们更容易快速地给您提供良好的反馈。

您发现 bug 了吗？

🤗 LeRobot 库之所以稳健可靠，要归功于那些向我们报告问题的用户。因此，感谢您报告问题。

首先，我们非常希望您能确保这个 bug 之前没有被报告过（请使用 Github Issues 下的搜索栏进行搜索）。

没找到？ :( 为了我们能快速处理，请遵循以下步骤：

提供您的 操作系统类型和版本、Python 和 PyTorch 的版本。
提供一个简短、独立的代码片段，使我们能够在 30 秒内复现该 bug。
如果引发了异常，请提供完整的追溯信息。
附上任何您认为有帮助的其他附加信息，如截图。

您想要一个新功能吗？

一个好的功能请求应包含以下几点：

首先是动机

这是否与使用该库时遇到的问题/挫败感有关？如果是，请解释原因。最好能提供一个代码片段来演示该问题。
这是否与您某个项目的需求有关？我们很乐意了解！
这是您自己开发的功能，并认为可以造福社区吗？太棒了！请告诉我们它为您解决了什么问题。

写一个段落来描述该功能。
提供一个代码片段来演示其未来的用法。
如果这与某篇论文有关，请附上链接。
附上任何您认为有帮助的附加信息（图纸、截图等）。

如果你的问题写得很好，那么在你发布时，问题就已经解决了 80%。

添加新的策略、数据集或环境

请参考我们对数据集、策略以及环境（aloha、xarm、pusht）的实现，并遵循相同的 API 设计。

当实现一个新的可由 LeRobotDataset 加载的数据集时，请遵循以下步骤：

在 `lerobot/__init__.py` 中更新 `available_datasets_per_env`

在实现一个新的环境（例如 `gym_aloha`）时，请遵循以下步骤：

在 `lerobot/__init__.py` 中更新 `available_tasks_per_env` 和 `available_datasets_per_env`

在实现一个新的策略类（例如 `DiffusionPolicy`）时，请遵循以下步骤：

在 `lerobot/__init__.py` 中更新 `available_policies` 和 `available_policies_per_env`
设置所需的 `name` 类属性。
通过导入你的新策略类来更新 `tests/test_available.py` 中的变量。

提交拉取请求（PR）

在编写代码之前，我们强烈建议您搜索现有的 PR 或问题，以确保没有其他人已经在做同样的事情。如果您不确定，最好先开一个问题来获取一些反馈。

你需要具备基本的 `git` 熟练度才能为 🤗 LeRobot 做出贡献。`git` 不是最容易使用的工具，但它有最好的手册。在 shell 中输入 `git --help` 即可享受。如果你喜欢书籍，Pro Git 是一个非常好的参考。

请按照以下步骤开始贡献：

通过点击仓库页面上的“Fork”按钮，Fork 仓库。这会在您的 GitHub 用户账户下创建一份代码副本。
将您的 fork 克隆到本地磁盘，并将基础仓库添加为远程仓库。以下命令假设您已将公共 SSH 密钥上传到 GitHub。更多信息请参阅以下指南。
```
git clone git@github.com:<your Github handle>/lerobot.git
cd lerobot
git remote add upstream https://github.com/huggingface/lerobot.git
```
为您的开发更改创建一个新分支，并为您处理的每个新 PR 都这样做。

首先将你的 `main` 分支与 `upstream/main` 分支同步（更多详情请参阅 GitHub 文档）
```
git checkout main
git fetch upstream
git rebase upstream/main
```
一旦您的 `main` 分支同步完成，请从该分支创建一个新分支
```
git checkout -b a-descriptive-name-for-my-changes
```
🚨 不要在 `main` 分支上工作。
对于开发，我们建议使用 `poetry` 或 `uv` 等工具，而不是仅仅使用 `pip`，以便轻松跟踪我们的依赖项。请按照安装 poetry（使用版本 >=2.1.0）或安装 uv的说明进行操作，如果您还没有其中之一的话。

使用 conda 或 miniconda 设置开发环境
```
conda create -y -n lerobot-dev python=3.10 && conda activate lerobot-dev
```
如果你正在使用 `uv`，它可以管理 python 版本，所以你可以这样做
```
uv venv --python 3.10 && source .venv/bin/activate
```
要开发 🤗 LeRobot，您至少需要安装 `dev` 和 `test` 额外依赖项以及核心库

使用 `poetry`
```
poetry sync --extras "dev test"
```
使用 `uv`
```
uv sync --extra dev --extra test
```
您也可以安装项目及其所有依赖项（包括环境）

使用 `poetry`
```
poetry sync --all-extras
```
使用 `uv`
```
uv sync --all-extras
```
注意： 如果您不使用 `--all-extras` 安装模拟环境，在本地运行 pytest 套件时，需要这些环境的测试将被跳过。但是，它们*将*在 CI 中进行测试。通常，我们建议您在推送之前安装所有内容并进行本地测试。

无论您选择哪个命令来安装项目（例如 `poetry sync --all-extras`），当拉取包含更新版 `pyproject.toml` 和 `poetry.lock` 的代码时，您都应该再次运行该命令，以便将您的虚拟环境与新的依赖项同步。

`pip install some-package` 的等效操作就是

使用 `poetry`
```
poetry add some-package
```
使用 `uv`
```
uv add some-package
```
当对 `pyproject.toml` 的 poetry 部分进行更改时，您应该运行以下命令来锁定依赖项。使用 `poetry`
```
poetry lock
```
使用 `uv`
```
uv lock
```
在你的分支上开发功能。

在开发功能时，您应该确保测试套件能够通过。您应该像这样运行受更改影响的测试（请参见下面关于环境变量的解释）
```
pytest tests/<TEST_TO_RUN>.py
```
遵循我们的风格。

lerobot 依赖 `ruff` 来统一格式化其源代码。设置 pre-commit，使其作为 Git 提交钩子自动运行这些检查。

安装 `pre-commit` 钩子
```
pre-commit install
```
您可以随时对已暂存的文件运行这些钩子，使用命令：
```
pre-commit
```
当您对更改满意后，使用 `git add` 添加已更改的文件，并使用 `git commit` 进行提交以在本地记录您的更改
```
git add modified_file.py
git commit
```
注意，如果您已经提交了一些格式错误的更改，您可以使用
```
pre-commit run --all-files
```
请撰写良好的提交信息。

定期将您的代码副本与原始仓库同步是一个好主意。这样您可以快速了解更改情况。
```
git fetch upstream
git rebase upstream/main
```
使用以下命令将更改推送到您的账户
```
git push -u origin a-descriptive-name-for-my-changes
```
一旦您满意（并且下面的清单也满意了），请转到您在 GitHub 上的 fork 网页。点击“Pull request”，将您的更改发送给项目维护者进行审查。
如果维护者要求您进行更改，这很正常。核心贡献者也会遇到这种情况！为了让每个人都能看到拉取请求中的更改，请在您的本地分支中工作，并将更改推送到您的 fork。它们将自动出现在拉取请求中。

检查清单

您的拉取请求标题应是其贡献的摘要；
如果您的拉取请求解决了某个问题，请在拉取请求描述中提及问题编号，以确保它们被链接起来（并且查阅该问题的人知道您正在处理它）；
要表示工作正在进行中，请在标题前加上 `[WIP]`，或者最好将 PR 标记为草稿 PR。这有助于避免重复工作，并将其与准备合并的 PR 区分开来；
确保现有测试通过；

测试

包含一个广泛的测试套件，用于测试库的行为和几个示例。库测试可以在 tests 文件夹中找到。

安装 git lfs 以检索测试工件（如果您还没有）。

在 Mac 上

brew install git-lfs
git lfs install

在 Ubuntu 上

sudo apt-get install git-lfs
git lfs install

如果它们不在 tests/artifacts 中，请拉取工件

git lfs pull

我们使用 `pytest` 来运行测试。从仓库的根目录，以下是如何使用 `pytest` 为库运行测试：

python -m pytest -sv ./tests

您可以指定一个更小的测试集，以便只测试您正在处理的功能。

< > 在 GitHub 上更新