Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
286 lines (194 loc) · 6.69 KB

CONTRIBUTING.md

File metadata and controls

286 lines (194 loc) · 6.69 KB

Contributing to Lotus

Thank you for your interest in contributing to Lotus! This document provides guidelines and information for contributors.

Table of Contents

Getting Started

Before contributing, please:

  1. Read this contributing guide
  2. Check existing issues and pull requests to avoid duplicates
  3. Join our community discussions
  4. Familiarize yourself with the codebase

Development Setup

Prerequisites

  • Python 3.10
  • Git
  • Conda (recommended) or virtual environment
  • uv (for dependency management)

Setup Instructions

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone git@github.com:lotus-data/lotus.git
cd lotus

# Install lotus and all dependencies (including dev dependencies)
uv sync --dev

# Install pre-commit hooks
uv run pre-commit install

Contribution Workflow

1. Fork and Clone

  1. Fork the repository on GitHub
  2. Clone your fork locally
  3. Add the upstream repository as a remote
git remote add upstream git@github.com:lotus-data/lotus.git

2. Create a Feature Branch

git checkout -b feature/your-feature-name

3. Make Your Changes

  • Follow the code style guidelines
  • Write tests for new functionality
  • Update documentation as needed

4. Test Your Changes

# Run the test suite
uv run pytest

# Run linting
uv run pre-commit run --all-files

# Run type checking
uv run mypy lotus/

5. Commit Your Changes

Use conventional commit messages:

type(scope): description

Examples:
feat(models): add support for new model provider
fix(api): resolve authentication issue
docs(readme): update installation instructions

6. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a pull request using our template.

Pull Request Guidelines

Before Submitting

  • Code follows the project's style guidelines
  • Tests pass locally
  • Documentation is updated
  • No new warnings are generated
  • Self-review of your code

PR Template

Please include the following in your PR:

  • Purpose: Clear description of what the PR accomplishes
  • Test Plan: How you tested your changes
  • Test Results: Results of your testing
  • Documentation Updates: Any documentation changes needed
  • Type of Change: Bug fix, feature, breaking change, etc.
  • Checklist: Quality assurance items

Review Process

  1. Automated checks must pass (CI/CD)
  2. At least one maintainer must approve
  3. All conversations must be resolved
  4. Documentation updates may be required

Code Style and Standards

Python Code Style

  • Follow PEP 8 guidelines
  • Use type hints where appropriate
  • Keep functions and classes focused and well-documented
  • Use meaningful variable and function names

Pre-commit Hooks

We use pre-commit hooks to maintain code quality:

  • ruff: Linting and code formatting
  • mypy: Type checking

Running Code Quality Checks

# Install pre-commit hooks (uv handles the installation)
uv run pre-commit install

# Run all pre-commit hooks on all files
uv run pre-commit run --all-files

# To run a specific hook (e.g., ruff)
uv run pre-commit run ruff --all-files

# To run pre-commit checks before every commit (recommended), just commit as usual:
git commit -m "Your commit message"
# The hooks will run automatically

Testing Guidelines

Writing Tests

We maintain two test suites:

  • lotus/.github/tests: essential tests for CI/CD to ensure core functionality
  • lotus/tests: additional tests for comprehensive testing of non-core functionality and integrations

If you are unsure where to add your new tests, we recommend starting them within lotus/tests and highlighting your question in your PR, so that the maintainers can respond with their suggestions.

You can find useful documentation, conceptual explanations, and best practices for writing pytests here.

Our general guidelines for testing include the following:

  • Write tests for new functionality, ensuring full coverage of possible code paths and edge cases
  • Avoid writing tests that depend on specific model behaviors. For example, when writing a sem_map test, we would avoid assertions on the exact projection output, and instead write assertions that the expected column exists in the resulting dataframe with non-empty string attributes.
  • Use descriptive test names
  • Mock external dependencies

Running Tests

  • first export the following enviorment variables:
export ENABLE_OPENAI_TESTS="true"
export ENABLE_LOCAL_TESTS="true"
export OPENAI_API_KEY="<your key>"
  • then run your pytest
# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_models.py

# Run tests in parallel
uv run pytest -n auto

Documentation

Documentation Standards

  • Keep documentation up to date
  • Use clear, concise language
  • Include code examples
  • Update README.md for significant changes

Documentation Structure

  • README.md: Project overview and quick start
  • docs/: Detailed documentation
  • examples/: Code examples
  • Inline code comments for complex logic

Running Models

Lotus uses the litellm library to interface with various model providers. Here are some examples:

GPT-4o Example

from lotus.models import LM

lm = LM(model="gpt-4o")

Ollama Example

from lotus.models import LM

lm = LM(model="ollama/llama3.2")

vLLM Example

from lotus.models import LM

lm = LM(
    model='hosted_vllm/meta-llama/Meta-Llama-3-8B-Instruct',
    api_base='http://localhost:8000/v1',
    max_ctx_len=8000,
    max_tokens=1000
)

Getting Help

Community Resources

  • GitHub Discussions: For questions and general discussion
  • GitHub Issues: For bug reports and feature requests
  • Documentation: Check the README and examples folder

Before Asking for Help

  1. Check existing issues and discussions
  2. Read the documentation
  3. Try to reproduce the issue in a minimal environment
  4. Provide clear, detailed information about your problem

Contact Information

Thank you for contributing to Lotus! 🚀