wehub-resource-sync
136 lines
4.1 KiB
Markdown
136 lines
4.1 KiB
Markdown
# Contributing 👍🎉
|
|
|
|
First off, thank you for taking the time to contribute! 🎉👍
|
|
Check out the [online docs](https://docs.lmcache.ai/developer_guide/contributing.html) for a set of guidelines for contributing.
|
|
|
|
A summary of LMCache's current direction can be found at: [[Onboarding] Welcoming contributors with good first issues!](https://github.com/LMCache/LMCache/issues/627)
|
|
|
|
=======
|
|
|
|
## Becoming an LMCache Committer
|
|
|
|
To become a committer, you should:
|
|
|
|
- Have **more than 5 important features** merged.
|
|
- Have been **contributing for longer than 3 months**.
|
|
- Be [**nominated by an existing committer**](MAINTAINERS.md).
|
|
|
|
========
|
|
|
|
## Basics of LMCache dev
|
|
|
|
The default branch is `dev`. Base all new branches and pull requests against `dev`.
|
|
|
|
## Python Environment
|
|
|
|
We recommend using [uv](https://docs.astral.sh/uv/) to manage Python environments and dependencies:
|
|
|
|
```bash
|
|
# Create and activate a virtual environment
|
|
uv venv --python 3.12
|
|
source .venv/bin/activate
|
|
|
|
# Install dependencies
|
|
uv pip install vllm/sglang/other engines
|
|
|
|
# Install LMCache. Requires nvcc. Use --no-build-isolation to ensure torch compatibility.
|
|
uv pip install -e . --no-build-isolation
|
|
|
|
# For ROCm build
|
|
BUILD_WITH_HIP=1 pip install -e .
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Run standard test suite (mirrors CI)
|
|
pytest -xvs --ignore=tests/disagg \
|
|
--ignore=tests/v1/multiprocess/ \
|
|
--ignore=tests/v1/distributed/ \
|
|
--ignore=tests/skipped \
|
|
--ignore=tests/v1/storage_backend/test_eic.py
|
|
|
|
# Run a single test file
|
|
pytest -xvs tests/v1/test_cache_engine.py
|
|
|
|
# Run a single test
|
|
pytest -xvs tests/v1/test_cache_engine.py::test_function_name
|
|
```
|
|
|
|
Test dependencies: `uv pip install -r requirements/test.txt`
|
|
|
|
Pytest marker: `@pytest.mark.no_shared_allocator` disables the shared-allocator monkeypatch for a test.
|
|
|
|
### Testing Practices
|
|
|
|
- Write tests against the **public interface and docstring contract**, not the implementation. Test as if you don't know the internals — verify that behavior matches what the docstring describes.
|
|
- Avoid accessing private members in tests unless strongly needed.
|
|
- All new features and bug fixes should include corresponding tests.
|
|
- Ensure existing tests still pass before submitting changes.
|
|
|
|
## Linting & Code Quality
|
|
|
|
```bash
|
|
# Run all checks (mirrors CI exactly)
|
|
pre-commit run --all-files
|
|
|
|
# Individual tools
|
|
ruff check . # Lint (E, F, B, SLF rules)
|
|
ruff format . # Format (line-length 88)
|
|
isort . # Import sorting (black profile, from_first=true)
|
|
mypy --config-file=pyproject.toml # Type checking
|
|
codespell --toml pyproject.toml # Spell checking
|
|
```
|
|
|
|
C++/CUDA files use clang-format (Google style, 80-col). Rust code in `rust/` uses `cargo fmt` and `cargo clippy`.
|
|
|
|
All Python files require an `# SPDX-License-Identifier: Apache-2.0` header as the first line.
|
|
|
|
### Import Ordering
|
|
|
|
Imports must follow this section-heading convention:
|
|
|
|
```python
|
|
# Standard
|
|
import os
|
|
|
|
# Third Party
|
|
import torch
|
|
|
|
# First Party
|
|
from lmcache.v1.config import LMCacheEngineConfig
|
|
|
|
# Local
|
|
from .utils import helper
|
|
```
|
|
|
|
### SLF (Private Member Access)
|
|
|
|
SLF lint rules are currently enforced by CI only in `lmcache/v1/multiprocess/` and `lmcache/v1/distributed/`. However, **all new code should follow SLF discipline regardless of location** — never access private members (prefixed with `_`) of other classes. Treat this as a project-wide coding standard for any new or modified code.
|
|
|
|
## Coding Conventions
|
|
|
|
### Type Hints
|
|
|
|
All functions and methods must have type hints for arguments and return values.
|
|
|
|
### Docstrings
|
|
|
|
Every public function and method must have a clear docstring covering:
|
|
- What the function does
|
|
- Arguments (with types and descriptions)
|
|
- Return values
|
|
- Raised exceptions (if any)
|
|
- Additional notes when behavior is non-obvious
|
|
|
|
### Encapsulation
|
|
|
|
Never access private members (prefixed with `_`) of other classes. Interact only through their public API.
|
|
|
|
### Code Organization
|
|
|
|
- **Module-level helper functions** go at the top of the file (after imports, before classes).
|
|
- **Private/helper methods** within a class go at the end of the class, after all public methods.
|