From Fork to Merge: Complete Flow
# 1. Clone after forking
git clone https://github.com//PhyAgentOS.git
cd PhyAgentOS
# 2. Add upstream for syncing
git remote add upstream https://github.com/SYSU-HCP-EAI/PhyAgentOS.git
# 3. Create branch (see naming suggestions below)
git checkout -b feat/my-robot-driver
# 4. Push to your Fork after development
git push origin feat/my-robot-driver
# 5. Go to GitHub and click "Open Pull Request" feat/xxx— New feature / new driverfix/xxx— Bug fixdocs/xxx— Documentation changesrefactor/xxx— Refactoring without behavior changes
Three Mandatory Pre-Commit Checks
It is recommended to complete checks locally first to avoid fixing CI failures after submission. All three checks are configured in pyproject.toml and can be executed directly.
Code Formatting
ruff check .
ruff format .Unit Tests
pytest tests/
# Or run only related tests
pytest tests/test_hal_base_driver.pyInstall Dev Dependencies
pip install -e ".[dev]"Type Checking (Recommended)
# Read through the method call sites you changed,
# confirm no obvious type mismatchesPR Description Standards
Please follow the template below when writing PR descriptions. Clear documentation helps accelerate the review process.
## What Changed
One-sentence summary + list key files and logic changes.
## How Verified
- What commands did you run locally? Results?
- Real/simulator verification logs or screenshots (required for driver/plugin)
- Does documentation render correctly (required for docs)
## Related Issue
Closes #123Driver / Plugin PR
Must include: profile path, startup command, and at least one action execution record.
Bug Fix PR
Must explain: how to reproduce, root cause, and post-fix verification results. Reference the Issue if applicable.
Docs PR
Must explain: which pages changed, why, and what needs special attention.
Issue Categories: Align Before You Start
If you are unsure about the implementation approach, it is recommended to open an Issue for discussion first. Below are commonly used labels — correct labeling helps maintainers respond more quickly.
| Label | When to Use | Best to Include |
|---|---|---|
| bug | Malfunction, crash, or behavior inconsistent with docs | Reproduction steps, environment info, error logs |
| feature | Want new capability, tool, or protocol field | Use case, expected interface, willingness to implement |
| driver-request | Want support for a new robot or hardware | Device model, SDK availability, progress status |
| documentation | Docs missing, wrong, or unclear | Specific page, current content, suggested fix |
| good first issue | Simple tasks suitable for newcomers | Clear scope, reference to existing code |
Merge Requirements
The purpose of review is to ensure the next person can understand and maintain the code. All four must be green before merging:
- CI all green — Lint and tests must pass.
- At least 1 Approve — Core architecture or protocol changes should wait for 2 Maintainers.
- Self-explanatory — Complex logic should have comments or documentation.
- No breaking changes to existing interfaces — Unless a migration plan is explained in the Issue/PR.
First Contribution? Start Here
No Hardware Needed
- Fix documentation typos or dead links
- Add test cases for existing drivers
- Improve docs site styling or navigation
With Hardware, Even Better
- Write a minimal driver + profile for a new robot
- Contribute a ROS2 adapter template
- Write a real-device deployment README