Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
81 lines (62 loc) · 4.39 KB

CONTRIBUTING.md

File metadata and controls

81 lines (62 loc) · 4.39 KB
Raw

Contributing to UniLab

Languages: English | 简体中文

Development Environment Setup

  1. Fork and clone the repository.
  2. Install dependencies for your platform:
    • macOS (MPS, installs PyPI torch wheels): make setup-motrix (or make setup-mujoco)
    • Linux default (installs PyTorch cu128 wheels; requires an NVIDIA GPU/driver supported by current PyTorch cu128 wheels): make setup
    • Linux AMD / ROCm workstation: make sync-rocm, then run commands with uv run --no-sync ...
    • For direct uv setup, use uv sync --extra mujoco --extra motrix; replace it with --extra mujoco or --extra motrix for a single backend
    • Physics adapters are supplied by the production PyPI package unisim-core>=0.1.14 (import namespace unisim).
  3. Create a branch such as git checkout -b docs/improve-readme or git checkout -b fix/backend-bug.

Development Rules

  • Always use uv run; do not invoke python outside uv run
  • Run make check before code-related commits
  • Keep backup files, temporary exports, and legacy compatibility copies out of the source tree; do not commit artifacts such as *.bak, *.tmp, *.old, *.orig, or editor backup files ending in ~
  • For user-facing workflow changes, keep README.md, CONTRIBUTING.md, and the matching localized docs under docs/ in sync
  • Do not add new owner logic under src/unilab/utils/; the current src/unilab/utils/*.py files are transition shims only and are scheduled for removal in 0.2.0
  • Name new owner modules and packages after their responsibility: prefer singular nouns, use plural only for collection-valued contracts, and reserve suffixes such as _factory for factory modules
  • Use English for code comments, public API docstrings, internal implementation notes, TODO/FIXME entries, and config comments. Keep Chinese prose in Chinese documentation under docs/sphinx/source/zh_CN/; do not duplicate localized explanations inside source comments.

Read Before You Start

Common Commands

make format         # ruff format + ruff check --fix
make sync-rocm      # Linux AMD / ROCm >= 7.1: sync deps and install torch==2.11.0+rocm7.2
make type           # mypy src/unilab + pyright
make check          # format + type (required before code-related commits)
make test           # non-slow tests
make test-cov       # non-slow tests + coverage report
make test-slow      # slow integration and training smoke tests
make test-all       # make check + make test-cov + benchmark entrypoint smoke

Commit Conventions

Use Conventional Commits:

  • feat: new feature
  • fix: bug fix
  • docs: documentation update
  • style: formatting only, no logic change
  • refactor: code refactor
  • test: test-related change
  • chore: build or tooling

Pull Request Workflow

  1. Choose and record the intended PR base before development.
  2. Run focused checks for the changed contract, then make test-all on the final local head before creating or updating the PR.
  3. Link the driving issue and record the exact validation commands, results, and backend/platform impact in the PR template.
  4. Complete review. A PR to main also waits for applicable current-head remote CI; another base uses local validation and review, with remote CI run by the later PR that reaches main.

Scope, authorization, roadmap branch, ADR, and release rules live in the Collaboration Workflow.

Issue Reports

Use GitHub Issues to report bugs or propose features.

Deep References