Контрибуция в LiteLLM: чек-лист для PR и тестов

Title:

URL Source: https://raw.githubusercontent.com/BerriAI/litellm/litellm_internal_staging/CONTRIBUTING.md

Markdown Content: # Contributing to LiteLLM

Thank you for your interest in contributing to LiteLLM! We welcome contributions of all kinds - from bug fixes and documentation improvements to new features and integrations.

## **Checklist before submitting a PR**

Here are the core requirements for any PR submitted to LiteLLM:

- [ ] **Sign the Contributor License Agreement (CLA)** - [see details](#contributor-license-agreement-cla) - [ ] **Keep scope isolated** - Your changes should address 1 specific problem at a time

#### Proxy (Backend) PRs

- [ ] **Add testing** - Adding at least 1 test is a hard requirement - [see details](#adding-testing) - [ ] **Ensure your PR passes all checks**: - [ ] [Unit Tests](#running-unit-tests) - `make test-unit` - [ ] [Linting / Formatting](#running-linting-and-formatting-checks) - `make lint`

#### UI PRs

- [ ] **Ensure the UI builds successfully** - `npm run build` - [ ] **Ensure all UI unit tests pass** - `npm run test` - [ ] **Add tests for new components or logic** - If you are adding a new component or new logic, add corresponding tests

## **Contributor License Agreement (CLA)**

Before contributing code to LiteLLM, you must sign our [Contributor License Agreement (CLA)](https://cla-assistant.io/BerriAI/litellm). This is a legal requirement for all contributions to be merged into the main repository.

**Important:** We strongly recommend reviewing and signing the CLA before starting work on your contribution to avoid any delays in the PR process.

## Quick Start

### 1. Setup Your Local Development Environment

```bash # Fork the repository on GitHub (click the Fork button at https://github.com/BerriAI/litellm) # Then clone your fork locally git clone https://github.com/YOUR_USERNAME/litellm.git cd litellm

# Create a new branch for your feature (see "Commit and Branch Conventions" below) git checkout -b feature/your-feature

# Install development dependencies make install-dev

# Install git hooks that enforce commit + branch conventions (one-time, opt-in) make install-hooks

# Verify your setup works make help ```

That's it! Your local development environment is ready.

## Commit and Branch Conventions

Commits follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) and branches follow [Conventional Branches](https://conventional-branch.github.io/). Run `make install-hooks` once per clone to enable the local git hooks that enforce these — see the [contributor docs](https://docs.litellm.ai/docs/extras/contributing_code#commit-and-branch-conventions) for the full type list, examples, the protected-branch bypass list, and how to opt out.

### 2. Development Workflow

Here's the recommended workflow for making changes:

```bash # Make your changes to the code # ...

# Format your code (auto-fixes formatting issues) make format

# Run all linting checks (matches CI exactly) make lint

# Run unit tests to ensure nothing is broken make test-unit

# Commit your changes (must follow Conventional Commits — see above) git add . git commit -m "feat(scope): your descriptive commit message"

# Push and create a PR (branch must follow Conventional Branches — see above) git push origin feature/your-feature ```

## Adding Testing

**Adding at least 1 test is a hard requirement for all PRs.**

### Where to Add Tests

Add your tests to the [`tests/test_litellm/` directory](https://github.com/BerriAI/litellm/tree/main/tests/test_litellm).

- This directory mirrors the structure of the `litellm/` directory - **Only add mocked tests** - no real LLM API calls in this directory - For integration tests with real APIs, use the appropriate test directories

### File Naming Convention

The `tests/test_litellm/` directory follows the same structure as `litellm/`:

- `litellm/proxy/caching_routes.py` → `tests/test_litellm/proxy/test_caching_routes.py` - `litellm/utils.py` → `tests/test_litellm/test_utils.py`

### Example Test

```python import pytest from litellm import completion

def test_your_feature(): """Test your feature with a descriptive docstring.""" # Arrange messages = [{"role": "user", "content": "Hello"}] # Act # Use mocked responses, not real API calls # Assert assert expected_result == actual_result ```

## Running Tests and Checks

### Running Unit Tests

Run all unit tests (uses parallel execution for speed):

```bash make test-unit ```

If you're running broader test suites, proxy tests, or anything that touches PostgreSQL-backed fixtures/plugins, install the full local test environment first:

```bash make install-test-deps ```

This syncs the locked test environment used across the repo, including `psycopg` v3 plus `psycopg-binary` (used by `pytest-postgresql`), `psycopg2-binary` (used by some proxy E2E tests), and a generated Prisma client for DB-backed proxy tests, so pytest startup matches CI without manual package installs.

Run specific test files: ```bash uv run pytest tests/test_litellm/test_your_file.py -v ```

### Running Linting and Formatting Checks

Run all linting checks (matches CI exactly):

```bash make lint ```

Individual linting commands: ```bash make format-check # Check Black formatting make lint-ruff # Run Ruff linting make lint-basedpyright # Run basedpyright type checking make check-circular-imports # Check for circular imports make check-import-safety # Check import safety ```

Apply formatting (auto-fixes issues): ```bash make format ```

> **Black formatting is enforced in CI.** All PRs must pass the Black formatting check. > > - **AI coding agents** (Claude Code, Copilot, Cursor, etc.): `AGENTS.md` and `CLAUDE.md` instruct agents to run `poetry run black .` before committing. > - **VS Code users**: Install the [Black Formatter extension](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter) and enable format-on-save: > ```json > { > "[python]": { > "editor.defaultFormatter": "ms-python.black-formatter", > "editor.formatOnSave": true > } > } > ```

### CI Compatibility

To ensure your changes will pass CI, run the exact same checks locally:

```bash # This runs the same checks as the GitHub workflows make lint make test-unit ```

For exact CI compatibility (pins OpenAI version like CI): ```bash make install-dev-ci # Installs exact CI dependencies ```

## Available Make Commands

Run `make help` to see all available commands:

```bash make help # Show all available commands make install-dev # Install development dependencies make install-proxy-dev # Install proxy development dependencies make install-test-deps # Install the full local test environment make format # Apply Black code formatting make format-check # Check Black formatting (matches CI) make lint # Run all linting checks make test-unit # Run unit tests make test-integration # Run integration tests make test-unit-helm # Run Helm unit tests ```

## Code Quality Standards

LiteLLM follows the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html).

Our automated quality checks include: - **Black** for consistent code formatting - **Ruff** for linting and code quality - **basedpyright** for static type checking - **Circular import detection** - **Import safety validation**

All checks must pass before your PR can be merged.

## Common Issues and Solutions

### 1. Linting Failures

If `make lint` fails:

1. **Formatting issues**: Run `make format` to auto-fix 2. **Ruff issues**: Check the output and fix manually 3. **basedpyright issues**: Add proper type hints 4. **Circular imports**: Refactor import dependencies 5. **Import safety**: Fix any unprotected imports

### 2. Test Failures

If `make test-unit` fails:

1. Check if you broke existing functionality 2. Add tests for your new code 3. Ensure tests use mocks, not real API calls 4. Check test file naming conventions

### 3. Common Development Tips

- **Use type hints**: basedpyright requires proper type annotations - **Write descriptive commit messages**: Help reviewers understand your changes - **Keep PRs focused**: One feature/fix per PR - **Test edge cases**: Don't just test the happy path - **Update documentation**: If you change APIs, update docs

## Building and Running Locally

### LiteLLM Proxy Server

To run the proxy server locally:

```bash # Install proxy dependencies make install-proxy-dev

# Start the proxy server uv run litellm --config your_config.yaml ```

### Docker Development

If you want to build the Docker image yourself:

```bash # Build using the non-root Dockerfile docker build -f docker/Dockerfile.non_root -t litellm_dev .

# Run with your config docker run \ -v $(pwd)/proxy_config.yaml:/app/config.yaml \ -e LITELLM_MASTER_KEY="sk-1234" \ -p 4000:4000 \ litellm_dev \ --config /app/config.yaml --detailed_debug ```

## UI Development

### 1. Setup Your Local UI Development Environment

```bash # Clone the repo (if you haven't already) git clone https://github.com/YOUR_USERNAME/litellm.git cd litellm

# Navigate to the UI dashboard directory cd ui/litellm-dashboard

# Install dependencies npm install

# Start the development server npm run dev ```

### 2. Adding UI Tests

If you are adding a **new component** or **new logic**, you must add corresponding tests.

### 3. Running UI Unit Tests

```bash npm run test ```

### 4. Building the UI

Ensure the UI builds successfully before submitting your PR:

```bash npm run build ```

## Submitting Your PR

1. **Push your branch**: `git push origin your-feature-branch` 2. **Create a PR**: Go to GitHub and open a pull request against [`litellm_internal_staging`](https://github.com/BerriAI/litellm/tree/litellm_internal_staging), which is the default base branch. Do not target `main`. 3. **Fill out the PR template**: Provide clear description of changes 4. **Wait for review**: Maintainers will review and provide feedback 5. **Address feedback**: Make requested changes and push updates 6. **Merge**: Once approved, your PR will be merged!

## Getting Help

If you need help:

- 💬 [Join our Discord](https://discord.gg/wuPM9dRgDw) - 💬 [Join our Slack](https://www.litellm.ai/support) - 📧 Email us: ishaan@berri.ai / krrish@berri.ai - 🐛 [Create an issue](https://github.com/BerriAI/litellm/issues/new)

## What to Contribute

Looking for ideas? Check out:

- 🐛 [Good first issues](https://github.com/BerriAI/litellm/labels/good%20first%20issue) - 🚀 [Feature requests](https://github.com/BerriAI/litellm/labels/enhancement) - 📚 Documentation improvements - 🧪 Test coverage improvements - 🔌 New LLM provider integrations

Thank you for contributing to LiteLLM! 🚀