Skip to content

Contributing to Speculators

Thank you for considering contributing to Speculators! We welcome contributions from the community to help improve and grow this project. This document outlines the process and guidelines for contributing.

How Can You Contribute?

There are many ways to contribute to Speculators:

  • Reporting Bugs: If you encounter a bug, please let us know by creating an issue.
  • Suggesting Features: Have an idea for a new feature? Open an issue to discuss it.
  • Improving Documentation: Help us improve our documentation by submitting pull requests.
  • Writing Code: Contribute code to fix bugs, add features, or improve performance.
  • Reviewing Pull Requests: Provide feedback on open pull requests to help maintain code quality.

Getting Started

Prerequisites

Before contributing, ensure you have the following installed:

  • Python 3.10 or higher
  • pip (Python package manager)
  • Tox
  • Git

Setting Up the Repository

You can either clone the repository directly or fork it if you plan to contribute changes back:

Option 1: Cloning the Repository

  1. Clone the repository to your local machine:
git clone https://github.com/vllm-project/speculators.git
cd speculators

Option 2: Forking the Repository

  1. Fork the repository by clicking the "Fork" button on the repository's GitHub page.

  2. Clone your forked repository to your local machine:

git clone https://github.com/<your-username>/speculators.git
cd speculators

Installing Dependencies

To install the required dependencies for the package and development, run:

pip install -e .[dev]

The -e flag installs the package in editable mode, allowing you to make changes to the code without reinstalling it. The [dev] part installs additional dependencies needed for development, such as testing and linting tools.

Note: the data generation components off speculators (i.e. src/speculators/data_generation) require a vLLM installation. Code in this module should be run in a separate environment, with vllm. This can be done by installing the datagen extra using pip install -e .[datagen] (or pip install -e .[datagen,dev] for development).

Code Style and Guidelines

We follow strict coding standards to ensure code quality and maintainability. Please adhere to the following guidelines:

  • Code Style: Use Ruff for formatting and linting.
  • Type Checking: Use Mypy for type checking.
  • Testing: Write unit tests for new features and bug fixes. Use pytest for testing.
  • Documentation: Update documentation for any changes to the codebase.

To ensure consistency and quality of the codebase, we use ruff for linting and styling, mypy for type checking, and mdformat for formatting Markdown files.

Code Quality and Style

To run all quality checks (linting, formatting, type checking):

make quality

To automatically fix style issues, use:

make style

Running Tests

For testing, we use pytest as our testing framework. We have different test suites for unit tests, integration tests, end-to-end tests, and data generation tests. To run the tests, you can use Tox, which will automatically create isolated environments for each test suite. Tox will also ensure that the tests are run in a consistent environment, regardless of where they are executed.

Running All Tests

To run all tests:

tox

Running Specific Tests

tox will set up the environment for the test environment for each test you run.

  • Unit tests (focused on individual components with mocking):
tox -e test-unit
  • Integration tests (focused on interactions between components ideally without mocking):
tox -e test-integration
  • End-to-end tests (focused on the entire system and user interfaces):
tox -e test-e2e
  • Data generation tests (focused on the data generation process):

Note: This creates an environment with the datagen extra installed (including vllm) and executes the tests in this environment.

tox -e test-datagen

Running Tests with Coverage

To ensure your changes are covered by tests, run:

tox -e test-unit -- --cov=speculators --cov-report=html

Review the coverage report to confirm that your new code is adequately tested.

DCO Signoff

We require a DCO signoff for all commits. For more information, see the DCO Signoff documentation.

# Sign off a commit as you're making it
git commit --signoff -m"my commit"

# Add a signoff to the last commit you made
git commit --amend --signoff

# Rebase your branch against master and sign off every commit in your branch
git rebase --signoff master

Submitting Changes

  1. Create a Branch: Create a new branch for your changes:
git checkout -b feature/your-feature-name

  1. Make Changes: Implement your changes in the appropriate files. Commit your changes with clear and descriptive commit messages.

  2. Update Documentation: Update or add documentation to reflect your changes. This includes updating README files, docstrings, and any relevant guides.

  3. Run Tests and Quality Checks: Before submitting your changes, ensure all tests pass and code quality checks are satisfied:

tox
  1. Push Changes: Push your branch to your forked repository (if you forked):
git push origin feature/your-feature-name
  1. Open a Pull Request: From the fork repository, use the contribute button to open a pull request to the original repository's main branch. Provide a clear description of your changes and link any related issues.

Reporting Issues

If you encounter a bug or have a feature request, please open an issue on GitHub. Include as much detail as possible, such as:

  • Steps to reproduce the issue
  • Expected and actual behavior
  • Environment details (OS, Python version, etc.)

Community Standards

We are committed to fostering a welcoming and inclusive community. Please read and adhere to our Code of Conduct.

Additional Resources

License

By contributing to Speculators, you agree that your contributions will be licensed under the Apache License 2.0.