bitroboticslab · Mr-tooth · Apr 18, 2026 · Apr 17, 2026 · Apr 18, 2026 · Apr 18, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,23 @@
+---
+name: Bug Report
+about: Report issues encountered during runtime
+title: "[Bug] Brief description of the problem"
+labels: bug
+assignees: ''
+---
+### Description
+Clear and concise description of the issue.
+### Reproduction Steps
+1. Run command: `...`
+2. Trigger operation: ...
+3. Error observed:
+```
+Paste full error log here
+```
+### Environment Information
+- Operating System: [e.g. Ubuntu 22.04 / macOS 13 / Windows 11]
+- Python Version: [e.g. 3.11]
+- RMP Version: [e.g. 0.8.0]
+- Installation Method: [Source install / pip install]
+### Additional Information
+Attach related screenshots, motion files, or robot models if applicable.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,13 @@
+---
+name: Feature Request
+about: Suggest new features or improve existing ones
+title: "[Feature] Brief description of the feature"
+labels: enhancement
+assignees: ''
+---
+### Feature Description
+Clear and concise description of the desired feature.
+### Use Case
+Explain the use case for this feature and why it is needed.
+### Implementation Suggestions
+If you have ideas for implementation, describe them here for reference.
diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md
@@ -0,0 +1,14 @@
+---
+name: Question
+about: Ask usage questions or seek clarification
+title: "[Question] Brief description of your question"
+labels: question
+assignees: ''
+---
+### Question Description
+Clear and concise description of your question.
+### What you have tried
+- [ ] Checked README documentation
+- [ ] Checked usage guides under docs directory
+- [ ] Searched existing issues and found no related content
+- [ ] Attempted troubleshooting on your own
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,22 @@
+### Description
+Clear and concise description of the changes in this PR:
+1. What does this change do?
+2. Why is this change needed?
+3. Link related issues (if any): Fixes #<issue-number>
+---
+### Type of Change
+Please check the applicable options:
+- [ ] 🐛 Bug fix (non-breaking change that fixes an issue)
+- [ ] ✨ New feature (non-breaking change that adds functionality)
+- [ ] 📝 Documentation update (only changes to documentation)
+- [ ] 🔨 Refactoring (code change that does not affect functionality)
+- [ ] ⚠️ Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Other (describe below):
+---
+### Checklist
+All items must be completed before PR review:
+- [ ] I have run `make check` locally and all checks pass
+- [ ] I have added/updated tests that prove my fix is effective or my feature works
+- [ ] I have updated relevant documentation (README, docs, etc.) to reflect my changes
+- [ ] My changes generate no new warnings
+- [ ] I have checked that my code follows the project's style guidelines
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,92 @@
+# Contributor Covenant Code of Conduct
+## Our Pledge
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+## Our Standards
+Examples of behavior that contributes to a positive environment for our
+community include:
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+Examples of unacceptable behavior include:
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+## Enforcement Responsibilities
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+## Scope
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+## Enforcement
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders at [opensource@bitroboticslab.com](mailto:opensource@bitroboticslab.com).
+All complaints will be reviewed and investigated promptly and fairly.
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+## Enforcement Guidelines
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+### 1. Correction
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+### 2. Warning
+**Community Impact**: A violation through a single incident or series
+of actions.
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+### 3. Temporary Ban
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+### 4. Permanent Ban
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+## Attribution
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+[homepage]: https://www.contributor-covenant.org
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,46 +1,51 @@
-# CONTRIBUTING.md
-
-Thanks for contributing to `robot-motion-player`.
-
-## Source of truth
-
-Before implementing changes, align with:
-- `docs/requirements.md`
-- `docs/design.md`
-- `docs/summary.md`
-- `AGENTS.md`
-
-## Local workflow
-
-1. Install development dependencies:
-   - `make install-dev`
-2. Run checks while iterating:
-   - `make lint`
-   - `make test-quick`
-3. Run full validation before opening a PR:
-   - `make check`
-
-## Required checks for PRs
-
-- Minimum: `make lint`
-- Expected for functional changes: `make test`
-- For release-related changes: `make release-check`
-- Optional local hygiene: `make precommit`
-
-## Changelog discipline
-
-- Add user-visible changes under `## [Unreleased]` in `CHANGELOG.md`.
-- Use Keep a Changelog sections (`Added`, `Changed`, `Fixed`).
-- Keep entries concise, behavior-oriented, and scoped to the same PR.
-
-## Release-sensitive change rules
-
-If your change touches release/version surfaces:
-- Follow `RELEASING.md`.
-- Keep version markers synchronized by role:
-  - `pyproject.toml` release version `X.Y.Z`
-  - `motion_player/__init__.py` fallback `X.Y.Z.dev0`
-  - `motion_player/cli/main.py` fallback `X.Y.Z.dev0`
-- Add/update `docs/releases/vX.Y.Z.md` for the target release.
-
-Avoid bundling unrelated refactors into release/version patches.
+# Contributing Guidelines
+We welcome all contributions to Robot Motion Player! This document outlines the process and standards for contributing.
+## 📋 Prerequisites
+1. Python 3.9+
+2. Conda (recommended for Pinocchio installation)
+3. All development dependencies installed: `pip install -e ".[all,dev]" && pre-commit install`
+## 🚀 Development Workflow
+1. **Fork the repository** and clone your fork locally
+2. **Create a new branch** for your feature/bugfix:
+   - Feature branches: `feature/your-feature-name`
+   - Bugfix branches: `fix/your-bugfix-name`
+   - Documentation branches: `docs/your-doc-name`
+3. **Make your changes** following the code standards below
+4. **✅ MANDATORY: Run full local checks using official make commands BEFORE submitting PR**
+   We strictly enforce using Makefile commands for consistency across all environments, DO NOT run lint/test manually:
+   ```bash
+   make check   # Run all required checks in one go (lint + full test suite)
+   # Or run separately if you need to debug:
+   make lint    # Run all pre-commit formatting & static analysis checks
+   make test    # Run full unit test suite
+   ```
+   *All checks must pass before PR submission. CI runs exactly the same Makefile commands, so if it passes locally it will pass CI.*
+5. **Commit your changes** with clear and descriptive commit messages following [Conventional Commits](https://www.conventionalcommits.org/) standard:
+   - `feat: add X feature`
+   - `fix: resolve Y bug`
+   - `docs: update Z documentation`
+   - `refactor: refactor A module`
+6. **Submit a Pull Request** to the `main` branch
+## 📝 PR Requirements
+All PRs must meet the following criteria to be merged:
+1. **CI Checks Pass**: All 9 CI checks must be green (lint, unit tests on all platforms)
+2. **Description Clear**: PR description must clearly explain what the change does, why it is needed, and link to related issues if applicable
+3. **Tests Added**: For new features or bugfixes, add corresponding unit tests to prevent regression
+4. **Documentation Updated**: If the change affects user-facing functionality, update README and related documentation
+5. **No Breaking Changes**: If your change introduces breaking changes, clearly mark it in the PR description and discuss with maintainers first
+## 🎯 Code Standards
+- Follow Python PEP 8 standards (enforced by Ruff)
+- Keep code modular and well-commented
+- Write type hints for all public functions and methods
+- Keep functions small and focused (single responsibility principle)
+## 🐛 Reporting Issues
+When submitting issues:
+1. Use the appropriate issue template (Bug Report / Feature Request / Question)
+2. Provide all required information (environment details, reproduction steps, error logs)
+3. For bug reports, include a minimal reproducible example if possible
+## 💬 Community
+If you have questions or need help:
+- Open a [Discussion](https://github.com/bitroboticslab/robot-motion-player/discussions)
+- Join our community chat (coming soon)
+## 📄 License
+By contributing to this project, you agree that your contributions will be licensed under the Apache 2.0 License.
diff --git a/README.md b/README.md
@@ -3,12 +3,16 @@
 
   # Robot Motion Player
 
-  **Visualize • Tune • Validate Robot Motion Data**
+  **Visualise • Tune • Validate Robot Motion Data**
 
+  [![CI Status][ci-badge]][ci-url]
   [![License][license-badge]](LICENSE)
   [![Python][python-badge]](https://www.python.org/)
+  [![GitHub Stars][star-badge]][star-url]
+  [![GitHub Forks][fork-badge]][fork-url]
+  [![Contributors][contrib-badge]][contrib-url]
 
-  [English](README.md) | [中文](docs/QUICKSTART_zh.md)
+  [English](README.md) | [中文](README_zh.md)
 </div>
 
 ---
@@ -72,21 +76,25 @@ Robot Motion Player is a standalone, cross-platform Python tool for visualizing,
 
 ---
 
-## Installation
-
-### Quick Install (Coming soon)
-
-For most users, install via `pip`:
+## 📦 Installation
+> PyPI packages are pending approval, source installation is recommended for now:
 
+### User Installation (Direct Usage)
 ```bash
-# Core + MuJoCo
-pip install robot-motion-player[mujoco]
-
-# With GUI support
-pip install robot-motion-player[mujoco,gui]
+git clone https://github.com/bitroboticslab/robot-motion-player.git
+cd robot-motion-player
+pip install ".[all]"
+```
 
-# Full features (including IK)
-pip install robot-motion-player[all]
+### Developer Installation (For Contributors)
+```bash
+git clone https://github.com/bitroboticslab/robot-motion-player.git
+cd robot-motion-player
+conda create -n rmp python=3.11 -y
+conda activate rmp
+conda install -c conda-forge pinocchio
+pip install -e ".[all,dev]"
+pre-commit install
 ```
 
 ### From Scripts (Linux, macOS, Windows)
@@ -119,6 +127,12 @@ pip install -e ".[all]"
 ```
 
 ## Quick Start
+### 🚀 2-Line Quick Run
+```bash
+git clone https://github.com/bitroboticslab/robot-motion-player.git && cd robot-motion-player
+pip install ".[all]" && motion_player gui --motion example/standard_dataset/run1_subject5_standard.pkl --robot example/robots/booster_t1/T1_23dof.xml
+```
+
 
 ### Try with Example Data
 
@@ -148,7 +162,7 @@ motion_player metrics \
 ## Documentation
 
 - 📖 [Quick Start Guide](docs/QUICKSTART_en.md)
-- 📖 [快速上手](docs/QUICKSTART_zh.md)
+- 📖 [Chinese Quick Start Guide](docs/QUICKSTART_zh.md)
 - 📖 [IK Usage Guide](docs/IK_USAGE.md)
 
 ---
@@ -165,6 +179,18 @@ Robot Motion Player is designed to integrate with:
 
 ---
 
+## ❓ Frequently Asked Questions
+### Q1: Installation fails with Pinocchio related errors?
+A: We recommend using Conda to install Pinocchio first: `conda install -c conda-forge pinocchio` before running `pip install`. For Windows users, this avoids compilation errors entirely.
+### Q2: Runtime error "file not found" for motion/robot files?
+A: Make sure you are running the command from the root of the cloned repository, or use absolute paths for the `--motion` and `--robot` parameters.
+### Q3: GUI fails to start or shows black screen?
+A: Ensure you have OpenGL 3.3+ support. For headless servers, use `xvfb-run` to run GUI commands in virtual display: `xvfb-run motion_player gui ...`
+### Q4: Video/GIF export fails?
+A: Install required system dependency: `ffmpeg` (required for video export). GIF export uses built-in PIL library and has no extra system dependencies.
+### Q5: Chinese path errors on Windows?
+A: Move the repository to a path without Chinese characters, or upgrade your Python version to 3.11+.
+
 ## Citing
 
 If you use Robot Motion Player in your research, please cite:
@@ -200,5 +226,13 @@ Built upon the shoulders of:
 - [GMR](https://github.com/YanjieZe/GMR) — Motion retargeting
 
 <!-- Links -->
+[ci-badge]: https://github.com/bitroboticslab/robot-motion-player/actions/workflows/ci.yml/badge.svg
+[ci-url]: https://github.com/bitroboticslab/robot-motion-player/actions/workflows/ci.yml
+[star-badge]: https://img.shields.io/github/stars/bitroboticslab/robot-motion-player
+[star-url]: https://github.com/bitroboticslab/robot-motion-player/stargazers
+[fork-badge]: https://img.shields.io/github/forks/bitroboticslab/robot-motion-player
+[fork-url]: https://github.com/bitroboticslab/robot-motion-player/network/members
+[contrib-badge]: https://img.shields.io/github/contributors/bitroboticslab/robot-motion-player
+[contrib-url]: https://github.com/bitroboticslab/robot-motion-player/graphs/contributors
 [license-badge]: https://img.shields.io/badge/License-Apache%202.0-blue.svg
 [python-badge]: https://img.shields.io/badge/Python-3.9%2B-blue