Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
74 lines (56 loc) · 3.77 KB

CONTRIBUTING.md

File metadata and controls

74 lines (56 loc) · 3.77 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): uv sync
    • Linux default (installs PyTorch cu128 wheels; requires an NVIDIA GPU/driver supported by current PyTorch cu128 wheels): uv sync
    • Linux AMD / ROCm workstation: make sync-rocm, then run commands with uv run --no-sync ...
    • When you need Motrix, append --extra motrix
  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

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

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. For code or config changes, run make check locally so lint, mypy, and pyright pass.
  2. For code changes, run make test locally so non-slow tests pass.
  3. If you touched IPC, Runner, or Config, add or update the matching tests.
  4. For docs-only changes, run uv run pytest tests/scripts/test_check_docs.py -q at minimum.
  5. If you touched repository hygiene rules, run uv run pytest tests/scripts/test_repo_hygiene.py -q.
  6. Link the relevant GitHub issue and fill in validation plus impact scope in the PR template.
  7. Open the PR against main and wait for green CI.
  8. Wait for code review.

Issue Reports

Use GitHub Issues to report bugs or propose features.

Deep References