如何為 🤗 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 上更新