Skip to content

Contributing to Quiver

Want to help make Quiver even better? We'd love your contributions! This guide will help you get started with the development process. 🚀

Getting Started

Prerequisites

Before you begin, make sure you have:

  • Go 1.18 or later
  • Git
  • A C compiler (for DuckDB integration)
  • Your favorite code editor

Setting Up the Development Environment

  1. Fork the repository on GitHub
  2. Clone your fork:
git clone https://github.com/TFMV/quiver.git
cd quiver
  1. Add the upstream repository:
git remote add upstream https://github.com/TFMV/quiver.git
  1. Install dependencies:
go mod download

Development Workflow

Creating a Branch

Create a new branch for your feature or bugfix:

git checkout -b feature/your-feature-name

Use a descriptive name that reflects what you're working on.

Making Changes

  1. Make your changes to the codebase
  2. Write or update tests for your changes
  3. Run the tests to make sure everything passes:
go test ./...
  1. Run the benchmarks to ensure performance is maintained:
go test -bench=. -benchmem ./...

Coding Standards

We follow standard Go coding conventions:

  • Use gofmt to format your code
  • Follow the Go Code Review Comments
  • Write clear, concise comments
  • Add documentation for public functions

Commit Messages

Write clear, concise commit messages that explain your changes:

feat: Add support for custom distance functions

This commit adds the ability for users to define and use custom
distance functions for vector similarity calculations.

We follow the Conventional Commits format:

  • feat: for new features
  • fix: for bug fixes
  • docs: for documentation changes
  • test: for changes to tests
  • perf: for performance improvements
  • refactor: for code refactoring
  • chore: for changes to the build process or auxiliary tools

Submitting a Pull Request

  1. Push your branch to your fork:
git push origin feature/your-feature-name
  1. Go to the Quiver repository and create a new pull request
  2. Provide a clear description of your changes
  3. Link any related issues

Testing

Running Tests

Run the full test suite:

go test ./...

Run tests with verbose output:

go test -v ./...

Run a specific test:

go test -v -run TestSearchWithFilter ./...

Running Benchmarks

Run all benchmarks:

go test -bench=. -benchmem ./...

Run a specific benchmark:

go test -bench=BenchmarkSearch -benchmem ./...

Compare benchmark results before and after your changes:

# Before changes
go test -bench=. -benchmem ./... > before.txt
# After changes
go test -bench=. -benchmem ./... > after.txt
# Compare
benchstat before.txt after.txt

Documentation

Updating Documentation

If you're adding new features or changing existing ones, please update the documentation:

  1. Update the relevant markdown files in the docs/ directory
  2. Update code comments, especially for exported functions
  3. Add examples if appropriate

Building the Documentation

Build the documentation site:

cd docs
mkdocs build

Preview the documentation locally:

cd docs
mkdocs serve

Then open http://localhost:8000 in your browser.

Getting Help

If you need help or have questions:

  • Open an issue on GitHub
  • Join our community discussions
  • Reach out to the maintainers

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

License

By contributing to Quiver, you agree that your contributions will be licensed under the project's MIT License.

Thank You

Your contributions make Quiver better for everyone. We appreciate your time and effort! 🙏