Contribution
開発環境とチェック
通常利用は Installation の uv add git+https://github.com/tetsugo02/roboloom.git --tag v0.2.0 を使います.以下はroboloom本体やdocsを変更する開発者向けです.Python 3.12〜3.14とuvを使い,repositoryをcloneしてそのrootで実行します.
git clone https://github.com/tetsugo02/roboloom.git
cd roboloom
uv sync --extra rakuda2 --extra test --group dev --group docs
uv run ruff format .
uv run ruff check .
uv run mypy src
uv run pyright
uv run pytest # 全test(軽量test + e2e)
uv run pytest -m "not e2e" # 軽量testのみ(dora dataflowを起動しない)
uv run pytest -m e2e # mock deviceでdoraを起動するe2eのみ
uv run --group docs python scripts/docs.py build
Pull Request では,GitHub Actions(.github/workflows/test.yml)が変更対象を確認し,source codeやtest・実行時依存・CI 設定等が変わっている場合のみ Python 3.12〜3.14 で ruff check .・mypy src・軽量test(pytest -m "not e2e")を実行して必須チェック用job Tests status を報告します(docs/**・README*.md・LICENSE・pyproject.toml のmetadataのみ等の変更時はtestをskipして Tests status を成功扱いにするため,必須チェックを有効にしてもmergeが詰まりません).main へmergeされた後はtestを再実行せず,.github/workflows/badges.yml がmerge元 PR のtest結果から badges branch上のstatus badge JSON を更新します(workflow_dispatch で手動実行した場合も更新します).mock deviceでdoraのprocessを起動するE2E test(.github/workflows/e2e.yml,3並列)は手動実行(workflow_dispatch)で,実機は使いません.
checkout内の模擬dataflowは uv run roboloom validate examples/mock/config.yaml と uv run roboloom run examples/mock/config.yaml で確認できます.保存には record または test extraが必要です.examples/ と scripts/ はcheckout用で,Git依存の利用者は自身の設定やPython scriptを使います.
模擬の設定の保存先は datasets/rakuda-mock です(option bilateral では datasets/rakuda-mock-bilateral).記録の形(featureの名前や形)を変えた後は,古いdataへ追記できません.古いdataは移すか,output を変えてください.画面確認のために既存dataを削除しないでください.
変更と無関係な整形差分は含めないでください.模擬試験・実data・実機検証は区別して報告します.
packageの著者・keyword・project URLは pyproject.toml の project.authors,project.keywords,project.urls で管理します.docsの著者とrepository linkは docs/base.yml の site_author,repo_name,repo_url に設定します.著者情報や公開先を変更するときは,両方を揃えて更新してください.
機能とdocsを一緒に更新する
機能追加・動作変更と同じ変更で,影響する docs/ を更新します.日本語(docs/ja/)と英語(docs/en/)の両方を同じ変更で更新し,ページ構成・見出し・code例・link先を揃えます.設定・既定値・CLI・Python API・制限事項と,実際の実装を揃えます.
| 変更 | 更新するページ |
|---|---|
| installや初回操作 | Get started と関係するtutorial |
| 機体や対応する組み合わせ | robots/<機体>/ のページ,対応表(get-started/support-matrix.md),機体のtutorial |
| sensorの設定・形式 | Sensors と対応機体の sensors.md |
| 操作入力・開始条件 | Controllers と対応機体の controllers.md |
| 方策・推論 | Policy |
| 記録の形式・dataset | Data と reference/dataset-features.md |
| API・CLI・設定の変更 | Reference(表の形)と関連するsample |
| 機能の検証の状態 | reference/status-labels.md と,そのlabelを付けたページ |
| 公開API・CLI・設定・対応機器の変更 | src/roboloom/agent_skills/roboloom/ のskill(SKILL.md と references/) |
新しいページは両言語の同じpathに置き,mkdocs.yml(日本語)と mkdocs.en.yml(英語)の nav に登録します.README.md(英語)・README.ja.md(日本語)と roboloom init が配布するtemplateのREADMEも,手順に影響があれば同時に更新します.現行codeとdocumentationが食い違っていた場合は,codeの規約を基準に修正し,食い違いを変更報告に記載します.
ページを移したり消したりしたら,docs/base.yml の redirect_maps に旧pathを登録します.Tutorials は手順,Reference は表による記述だけ,Explanation は背景と理由,と書き分けます.実機で確かめていない機能も載せますが,ページの冒頭か表の行に 状態label を付けます.設計案や過去の調査メモを,実機検証済みの仕様として案内しないでください.
docsの編集とpreview
ZensicalのMkDocs互換機能 を使います.言語ごとに設定を分け,共通設定は docs/base.yml に置きます.
| 言語 | Markdown | 設定 | 出力先 |
|---|---|---|---|
| 日本語 | docs/ja/ |
mkdocs.yml |
site/ja/ |
| 英語 | docs/en/ |
mkdocs.en.yml |
site/en/ |
uv run --group docs python scripts/docs.py build # 両言語をstrictでbuild
uv run --group docs python scripts/docs.py serve # 両言語をbuildして http://127.0.0.1:8000 で表示
uv run --group docs zensical serve # 日本語だけをlive reloadで表示
uv run --group docs zensical serve -f mkdocs.en.yml # 英語だけをlive reloadで表示
右上の言語切り替えは,site/ に両言語が並んでいるときに選んだ言語のホームへ移ります.片方の言語だけを zensical serve で開いているときは,切り替え先が表示されません.site/index.html はbrowserの言語に応じて ja/ か en/ へ転送します.生成物はGitへ追加しません.
fontと配色は docs/overrides/(main.html と assets/stylesheets/roboloom.css)で調整しています.
docs/ja/yam-safety-and-smoothness.md は過去の調査・設計メモとして残し,利用ガイドのbuild対象から除外しています.未実装の機能の設計案は,bilateral制御の設計 のように,冒頭で未実装と明示した上でContributionに置きます.
日本語の表記
英語由来の専門用語は,日本語の文中でも英語で書きます(カタカナにしません).綴りはcodeの識別子・APIの用語に揃えます(文中は follower,class名は Follower).
| 分野 | 例 |
|---|---|
| robot・制御・hardware | follower, sensor, gripper, tracker, motor, torque, camera, arm, bus, serial, port, driver, firmware, interface, watchdog, encoder, gain, latch |
| software・CLI・設定 | node, option, key, file, path, command, directory, process, thread, class, module, package, repository, template, project, session, log, build, test, error, flag, trigger, timeout |
| data・学習 | dataset, data, metadata, episode, checkpoint, chunk, epoch, model, sample, task, label, schema, vector, norm, skill, agent, coding agent |
| 音声・映像 | mel, mel power, mono, mic, sampling, stereo, channel, color, frame |
| 画面の概念 | tab, pane, panel, focus, menu, dialog, shortcut, tooltip, cursor, drag, scroll, layout, font |
- 一般的な外来語はカタカナのまま:ページ,ボタン,リスト,コピー,チェック,メモ,ガイド,ホーム,カード,サイズ,ゼロ,オン.
- 漢字の用語(方策,入力,記録,校正,遠隔操作)と製品名(PiPER, Pika, Rakuda2, LeRobot, RealSense, DIGIT)はそのまま.
- 新しいカタカナ用語や長音の揺れ(
センサ/センサー,グリッパ/グリッパー)を足さないでください.英語表記で統一します. - code例とplaceholderは英語ページと揃えます(
<follower>,<node>,{name: path},logs/<dataset name>-<time>/). - 見出しに英語を使っても,linkは既存の明示anchor(
{ #... })を使います.
GitHub Pagesへの公開
.github/workflows/docs.yml が両言語をstrictでbuildし,site/ 全体をGitHub Pagesへ公開します.公開先は 日本語 と English です.root URLではbrowserの言語に応じて転送します.
mainへのpush:docs/**,src/**(Python APIのページはdocstringから作る),mkdocs*.yml,scripts/docs.py,uv.lock,workflow自身の変更でbuild・公開します.main向けのpull request:同じfile群の変更でbuildだけを検証します.- Actionsの
Documentation→Run workflow:手動buildできます.公開するのはmainを選んだ場合だけです.
Python 3.12とuvを使い,uv sync --locked --only-group docs でlock済みのdocs依存だけをinstallします.続いて uv run --no-sync python scripts/docs.py build を実行し,成功した成果物を公開します.robot・sensor用の依存や実機接続は不要です.
初回はrepositoryの Settings → Pages → Build and deployment → Source を GitHub Actions に設定します(GitHubの設定手順).workflowを main に反映すると公開され,URLは github-pages environmentとActionsのdeploy結果に表示されます.buildが失敗した場合は公開しません.
新しいfollowerを足す
followerの機種(Follower のsubclass)は,安全に関わる性質 safety_traits(設定で変わる場合は declared_traits())を必ず宣言します.宣言のないclassはimportの時点でTypeErrorになります.値の意味は 設定 の「脱力したときと放置したときの性質」にあります.確かめていない性質は unknown にします.制御則で動く入力機器(JointInput のsubclass)も safety_traits を宣言します.姿勢で動かす(pose_ik)腕は,kinematics() でURDFの鎖(KinematicSpec:URDF,base,tip,関節)を返します.
roboloomを変えずに,自分のpackageから足す
roboloomに入っていないrobot,入力機器,sensor,controller,estimatorは,自分のcodeに置いたまま使えます.
- nodeのYAMLの
typeに,classをmodule:Classで書きます.importは,install済みのpackage,次に機体のdirectory(.roboloom/<robot>/)の順に探します. - nodeは1つずつ別のprocessで動き,それぞれが設定を読み直します.そのため,classは参照(
module:Class)で指定します.1つのprocessの中でregistryに登録しても,ほかのnodeからは見えません. - classは,その役割の基底class(
roboloom.robots.base.Follower,roboloom.inputs.base.JointInputとPoseInput,roboloom.core.source.Source,roboloom.controllers.base.Controller,roboloom.estimators.base.Estimator)を継承します.継承していないclassは,読み込みのときに拒否します. -
classが読むYAMLのkeyを
keysに書くと,それ以外のkeyは読み込みのときに拒否されます(綴りの誤りが黙って無視されません).keysを書かないclassは検査しません.from roboloom.robots.base import FOLLOWER_KEYS, Follower class MyArm(Follower): keys = (*FOLLOWER_KEYS, "address") -
followerに要るものは,関節名と単位,
safety_traits,open_bus(mock)が返すbus(read_positions,write_positions,enable_torque,close.roboloom.drivers.base.JointBus)です.mockがTrueのときは模擬のbusを返します. - simulatorは,同じfollowerのclassの後ろに別のbusを置きます.実機と同じ単位で話せば,datasetと方策を共有できます.
control:の制御則(roboloom.control)はDynamixel系のbus(count,mA,Operating Mode)を前提にしています.自前の位置制御を持つrobotでは使いません.
templateも自分の側に置けます.config.yaml,nodeのYAML,classのmodule,mock.yaml を1つのdirectory(またはpackageの template/)にまとめ,次のようにprojectを作ります.
uv run roboloom init lab_arm --template my_lab.robots.arm # packageの template/
uv run roboloom init lab_arm --template path/to/template # directory
uv run roboloom init lab_arm --update # templateが変わったあと
repositoryの examples/own_robot/ が,動く最小の見本です(followerのclass my_arm.py,方策で保持するだけの構成,模擬のbus).
uv run roboloom init lab_arm --template examples/own_robot
uv run roboloom infer lab_arm --mock --seconds 5 --plain
操作画面の拡張
新しい機種の機器accessはBackendへ置き,標準の状態項目を通知します.任意の機種別・役割別Presenterの明示登録,Backend契約,Pilot/MockBusでの検証は 操作画面 を参照してください.
release手順
version番号(pyproject.toml・uv.lock・src/roboloom/agent_skills/roboloom/SKILL.md・README*.md・docs/ の --tag)と CHANGELOG.md は scripts/release.py でまとめて更新し,Release PR を main へmergeした後にtag vX.Y.Z を push して公開します.
flowchart LR
P["scripts/release.py<br/>bump / set"] --> PR["Release PR<br/>test.yml (3.12-3.14) + docs.yml"]
PR --> M["main へmerge"]
M --> T["git tag -a vX.Y.Z<br/>git push origin vX.Y.Z"]
T --> R["release.yml<br/>整合確認・軽量test・uv build"]
R --> G["GitHub Release<br/>.whl / .tar.gz / SHA256SUMS.txt /<br/>attestation + git-cliff notes"]
| 段階 | command / trigger | 内容 |
|---|---|---|
| 1. 準備 | uv run python scripts/release.py bump minor(または set X.Y.Z) |
pyproject.toml・uv.lock・SKILL.md・--tag 参照・CHANGELOG.md(cliff.toml)を更新 |
| 2. 検証 | uv run python scripts/release.py check +test・docs build |
全fileのversion一致と PR 向けチェックを確認 |
| 3. PR merge | Release PR を main へmerge |
test.yml(Python 3.12〜3.14)と badges.yml が通過 |
| 4. 公開 | git tag -a vX.Y.Z -m "Release vX.Y.Z" && git push origin vX.Y.Z |
.github/workflows/release.yml がtag整合・ruff/mypy/pytest -m "not e2e"・uv build・wheel 隔離検証・SHA256SUMS.txt・build provenance attestation を実行し,GitHub Release を公開 |