diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..f2bc7c9637 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,274 @@ +# 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) +- [ ] **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` +- [ ] **Keep scope isolated** - Your changes should address 1 specific problem at a time + +## **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 +# Clone the repository +git clone https://github.com/BerriAI/litellm.git +cd litellm + +# Create a new branch for your feature +git checkout -b your-feature-branch + +# Install development dependencies +make install-dev + +# Verify your setup works +make help +``` + +That's it! Your local development environment is ready. + +### 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 +git add . +git commit -m "Your descriptive commit message" + +# Push and create a PR +git push origin your-feature-branch +``` + +## 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 +``` + +Run specific test files: +```bash +poetry 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-mypy # Run MyPy 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 +``` + +### 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 test dependencies (for running tests) +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 +- **MyPy** 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. **MyPy 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**: MyPy 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 +poetry 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 +``` + +## Submitting Your PR + +1. **Push your branch**: `git push origin your-feature-branch` +2. **Create a PR**: Go to GitHub and create a pull request +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) +- ๐Ÿ“ง 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! ๐Ÿš€ \ No newline at end of file diff --git a/Makefile b/Makefile index b25c95cd8f..9d67706f27 100644 --- a/Makefile +++ b/Makefile @@ -1,35 +1,90 @@ # LiteLLM Makefile # Simple Makefile for running tests and basic development tasks -.PHONY: help test test-unit test-integration lint format +.PHONY: help test test-unit test-integration test-unit-helm lint format install-dev install-proxy-dev install-test-deps install-helm-unittest check-circular-imports check-import-safety # Default target help: @echo "Available commands:" + @echo " make install-dev - Install development dependencies" + @echo " make install-proxy-dev - Install proxy development dependencies" + @echo " make install-dev-ci - Install dev dependencies (CI-compatible, pins OpenAI)" + @echo " make install-proxy-dev-ci - Install proxy dev dependencies (CI-compatible)" + @echo " make install-test-deps - Install test dependencies" + @echo " make install-helm-unittest - Install helm unittest plugin" + @echo " make format - Apply Black code formatting" + @echo " make format-check - Check Black code formatting (matches CI)" + @echo " make lint - Run all linting (Ruff, MyPy, Black check, circular imports, import safety)" + @echo " make lint-ruff - Run Ruff linting only" + @echo " make lint-mypy - Run MyPy type checking only" + @echo " make lint-black - Check Black formatting (matches CI)" + @echo " make check-circular-imports - Check for circular imports" + @echo " make check-import-safety - Check import safety" @echo " make test - Run all tests" - @echo " make test-unit - Run unit tests" + @echo " make test-unit - Run unit tests (tests/test_litellm)" @echo " make test-integration - Run integration tests" @echo " make test-unit-helm - Run helm unit tests" +# Installation targets install-dev: poetry install --with dev install-proxy-dev: - poetry install --with dev,proxy-dev + poetry install --with dev,proxy-dev --extras proxy -lint: install-dev +# CI-compatible installations (matches GitHub workflows exactly) +install-dev-ci: + pip install openai==1.81.0 + poetry install --with dev + pip install openai==1.81.0 + +install-proxy-dev-ci: + poetry install --with dev,proxy-dev --extras proxy + pip install openai==1.81.0 + +install-test-deps: install-proxy-dev + poetry run pip install "pytest-retry==1.6.3" + poetry run pip install pytest-xdist + cd enterprise && python -m pip install -e . && cd .. + +install-helm-unittest: + helm plugin install https://github.com/helm-unittest/helm-unittest --version v0.4.4 + +# Formatting +format: install-dev + cd litellm && poetry run black . && cd .. + +format-check: install-dev + cd litellm && poetry run black --check . && cd .. + +# Linting targets +lint-ruff: install-dev + cd litellm && poetry run ruff check . && cd .. + +lint-mypy: install-dev poetry run pip install types-requests types-setuptools types-redis types-PyYAML - cd litellm && poetry run mypy . --ignore-missing-imports + cd litellm && poetry run mypy . --ignore-missing-imports && cd .. -# Testing +lint-black: format-check + +check-circular-imports: install-dev + cd litellm && poetry run python ../tests/documentation_tests/test_circular_imports.py && cd .. + +check-import-safety: install-dev + poetry run python -c "from litellm import *" || (echo '๐Ÿšจ import failed, this means you introduced unprotected imports! ๐Ÿšจ'; exit 1) + +# Combined linting (matches test-linting.yml workflow) +lint: format-check lint-ruff lint-mypy check-circular-imports check-import-safety + +# Testing targets test: poetry run pytest tests/ -test-unit: - poetry run pytest tests/test_litellm/ +test-unit: install-test-deps + poetry run pytest tests/test_litellm -x -vv -n 4 test-integration: poetry run pytest tests/ -k "not test_litellm" -test-unit-helm: +test-unit-helm: install-helm-unittest helm unittest -f 'tests/*.yaml' deploy/charts/litellm-helm \ No newline at end of file diff --git a/README.md b/README.md index cbb6b4807b..66f2194114 100644 --- a/README.md +++ b/README.md @@ -341,7 +341,11 @@ curl 'http://0.0.0.0:4000/key/generate' \ ## Contributing -Interested in contributing? Contributions to LiteLLM Python SDK, Proxy Server, and contributing LLM integrations are both accepted and highly encouraged! [See our Contribution Guide for more details](https://docs.litellm.ai/docs/extras/contributing_code) +Interested in contributing? Contributions to LiteLLM Python SDK, Proxy Server, and LLM integrations are both accepted and highly encouraged! + +**Quick start:** `git clone` โ†’ `make install-dev` โ†’ `make format` โ†’ `make lint` โ†’ `make test-unit` + +See our comprehensive [Contributing Guide (CONTRIBUTING.md)](CONTRIBUTING.md) for detailed instructions. # Enterprise For companies that need better security, user management and professional support @@ -356,18 +360,41 @@ This covers: - โœ… **Custom SLAs** - โœ… **Secure access with Single Sign-On** -# Code Quality / Linting +# Contributing + +We welcome contributions to LiteLLM! Whether you're fixing bugs, adding features, or improving documentation, we appreciate your help. + +## Quick Start for Contributors + +```bash +git clone https://github.com/BerriAI/litellm.git +cd litellm +make install-dev # Install development dependencies +make format # Format your code +make lint # Run all linting checks +make test-unit # Run unit tests +``` + +For detailed contributing guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md). + +## Code Quality / Linting LiteLLM follows the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html). -We run: -- Ruff for [formatting and linting checks](https://github.com/BerriAI/litellm/blob/e19bb55e3b4c6a858b6e364302ebbf6633a51de5/.circleci/config.yml#L320) -- Mypy + Pyright for typing [1](https://github.com/BerriAI/litellm/blob/e19bb55e3b4c6a858b6e364302ebbf6633a51de5/.circleci/config.yml#L90), [2](https://github.com/BerriAI/litellm/blob/e19bb55e3b4c6a858b6e364302ebbf6633a51de5/.pre-commit-config.yaml#L4) -- Black for [formatting](https://github.com/BerriAI/litellm/blob/e19bb55e3b4c6a858b6e364302ebbf6633a51de5/.circleci/config.yml#L79) -- isort for [import sorting](https://github.com/BerriAI/litellm/blob/e19bb55e3b4c6a858b6e364302ebbf6633a51de5/.pre-commit-config.yaml#L10) +Our automated checks include: +- **Black** for code formatting +- **Ruff** for linting and code quality +- **MyPy** for type checking +- **Circular import detection** +- **Import safety checks** +Run all checks locally: +```bash +make lint # Run all linting (matches CI) +make format-check # Check formatting only +``` -If you have suggestions on how to improve the code quality feel free to open an issue or a PR. +All these checks must pass before your PR can be merged. # Support / talk with founders