Contributing to DeepSearcher

We welcome contributions from everyone. This document provides guidelines to make the contribution process straightforward.

Pull Request Process

Fork the repository and create your branch from master.
Make your changes.
Run tests and linting to ensure your code meets the project's standards.
Update documentation if necessary.
Submit a pull request.

Linting and Formatting

Keeping a consistent style for code, code comments, commit messages, and PR descriptions will greatly accelerate your PR review process. We require you to run code linter and formatter before submitting your pull requests:

To check the coding styles:

make lint

To fix the coding styles:

make format

Our CI pipeline also runs these checks automatically on all pull requests to ensure code quality and consistency.

Development Environment Setup with uv

DeepSearcher uses uv as the recommended package manager. uv is a fast, reliable Python package manager and installer. The project's pyproject.toml is configured to work with uv, which will provide faster dependency resolution and package installation compared to traditional tools.

Install Project in Development Mode(aka Editable Installation)

Install uv if you haven't already: Follow the offical installation instructions.

Clone the repository and navigate to the project directory:

git clone https://github.com/zilliztech/deep-searcher.git && cd deep-searcher

Synchronize and install dependencies:
```
uv sync
source .venv/bin/activate
```
uv sync will install all dependencies specified in uv.lock file. And the source .venv/bin/activate command will activate the virtual environment.
(Optional) To install all optional dependencies:
```
uv sync --all-extras --dev
```
(Optional) To install specific optional dependencies:
```
# Take optional `ollama` dependency for example
uv sync --extra ollama
```
For more optional dependencies, refer to the [project.optional-dependencies] part of pyproject.toml file.

Adding Dependencies

When you need to add new dependencies to the pyproject.toml file, you can use the following commands:

uv add <package_name>

DeepSearcher uses optional dependencies to keep the default installation lightweight. Optional features can be installed using the syntax deepsearcher[<extra>]. To add a dependency to an optional extra, use the following command:

uv add <package_name> --optional <extra>

For more details, refer to the offical Managing dependencies documentation.

Dependencies Locking

For development, we use lockfiles to ensure consistent dependencies. You can use

uv lock --check

to verify if your lockfile is up-to-date with your project dependencies.

When you modify or add dependencies in the project, the lockfile will be automatically updated the next time you run a uv command. You can also explicitly update the lockfile using:

uv lock

While the environment is synced automatically, it may also be explicitly synced using uv sync:

uv sync

Syncing the environment manually is especially useful for ensuring your editor has the correct versions of dependencies.

For more detailed information about dependency locking and syncing, refer to the offical Locking and syncing documentation.

Running Tests

Before submitting your pull request, make sure to run the test suite to ensure your changes haven't introduced any regressions.

Installing Test Dependencies

First, ensure you have pytest installed. If you haven't installed the development dependencies yet, you can do so with:

uv sync --all-extras --dev

This will install all development dependencies and optional dependencies including pytest and other testing tools.

Running the Tests

To run all tests in the tests directory:

uv run pytest tests

For more verbose output that shows individual test results:

uv run pytest tests -v

You can also run tests for specific directories or files. For example:

# Run tests in a specific directory
uv run pytest tests/embedding

# Run tests in a specific file
uv run pytest tests/embedding/test_bedrock_embedding.py

# Run a specific test class
uv run pytest tests/embedding/test_bedrock_embedding.py::TestBedrockEmbedding

# Run a specific test method
uv run pytest tests/embedding/test_bedrock_embedding.py::TestBedrockEmbedding::test_init_default

The -v flag (verbose mode) provides more detailed output, showing each test case and its result individually. This is particularly useful when you want to see which specific tests are passing or failing.

Developer Certificate of Origin (DCO)

All contributions require a sign-off, acknowledging the Developer Certificate of Origin. Add a Signed-off-by line to your commit message:

Signed-off-by: Your Name <your.email@example.com>