Contributing to Thermocline

Thank you for considering contributing to Thermocline! Whether you're fixing a typo, reporting a bug, or implementing a major feature, your contribution is valued.

Thermocline is developed and maintained by StronglyAI, Inc., and we believe open source thrives through community collaboration.

Code of Conduct

This project is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to support@strongly.ai.

Ways to Contribute

Contribution	Description
Bug Reports	Open an issue with steps to reproduce
Feature Requests	Suggest improvements
Code	Submit pull requests with fixes or features
Documentation	Fix typos, add examples, improve guides
Testing	Write tests, report test failures
Community	Help others in Discussions, write blog posts

Finding Something to Work On

• Good First Issues: Look for good first issue labels
• Help Wanted: Issues labeled help wanted are ready for community contribution

Comment on an issue before starting work to avoid duplicate effort and get guidance from maintainers.

Development Setup

Prerequisites

Tool	Version	Purpose
Git	2.x+	Version control
Go	1.21+	Coordinator, Controller, Operator, CLI
Rust	1.75+	Storage Engine, Gateway, Query Engine
Docker	24.x+	Container builds and local testing
kubectl	1.26+	Kubernetes interaction
Helm	3.x+	Deployment
Make	Any	Build automation

Clone and Build

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/thermocline.git
cd thermocline

# Add upstream remote
git remote add upstream https://github.com/strongly-ai/thermocline.git

# Install dependencies and build
make dev-setup
make build

# Run all tests
make test

# Start local dev environment (Docker Compose)
make dev-up

See the Development Guide for detailed setup instructions.

Making Changes

Branch Naming

Create a branch from main with a descriptive name:

# Sync with upstream
git fetch upstream
git checkout main
git merge upstream/main

# Create your branch
git checkout -b <type>/<short-description>

Branch types: feature/, fix/, docs/, refactor/, test/, chore/

Examples:

• feature/gcs-storage-adapter
• fix/cursor-timeout-handling
• docs/helm-configuration-guide

Commit Messages

Follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types: feat, fix, docs, style, refactor, perf, test, chore

Examples:

feat(storage): add Google Cloud Storage adapter

Implements the storage provider interface for GCS, including:
- Authentication via workload identity
- Multipart uploads for large files
- Retry logic with exponential backoff

Closes #234

fix(gateway): handle connection timeout during TLS handshake

Previously, connections would hang indefinitely if the TLS handshake
stalled. Now enforces a 30-second timeout.

Fixes #567

Keep Changes Focused

• One logical change per pull request -- Don't mix unrelated changes
• Small is beautiful -- Smaller PRs are easier to review and merge
• Break up large features -- Use feature flags or incremental PRs

Pull Request Process

Before Submitting

1. Sync with upstream -- Rebase on latest main
2. Run tests -- All tests must pass (make test)
3. Run linters -- Code must be lint-free (make lint)
4. Update documentation -- If your change affects user-facing behavior
5. Add tests -- New features need tests; bug fixes need regression tests

PR Template

## Description
Brief description of what this PR does.

## Motivation
Why is this change needed? Link to issue if applicable.

## Changes
- Bullet points of key changes

## Testing
How was this tested?

## Checklist
- [ ] Tests pass locally
- [ ] Linters pass
- [ ] Documentation updated (if applicable)

Review Process

1. Automated checks -- CI must pass (tests, lints, builds)
2. Maintainer review -- At least one maintainer approval required
3. Address feedback -- Respond to comments and make requested changes
4. Merge -- Maintainer merges when approved

We aim to provide initial review within 3 business days.

Coding Standards

Go

• Follow Effective Go guidelines
• Use gofmt for formatting and golangci-lint for linting
• Handle errors explicitly -- never ignore them
• Wrap errors with context: fmt.Errorf("fetch partitions: %w", err)

Rust

• Follow Rust API Guidelines
• Use rustfmt for formatting and clippy for linting
• Prefer Result over panics; use thiserror for error types
• Use tokio for all async code

General

• Clarity over cleverness -- Write code that's easy to understand
• Consistency -- Follow existing patterns in the codebase
• Comments explain why, not what -- Code should be self-documenting
• No dead code -- Remove unused code, don't comment it out

Testing Requirements

• New features must include tests
• Bug fixes must include regression tests
• Target coverage > 80% for new code

Type	Location	Command
Unit tests	*_test.go / #[cfg(test)]	make test-unit
Integration tests	tests/integration/	make test-integration
Compatibility tests	tests/compatibility/	make test-compatibility
End-to-end tests	tests/e2e/	make test-e2e

Writing Good Tests

• Test behavior, not implementation -- Tests should survive refactoring
• Use table-driven tests -- For testing multiple inputs
• Test edge cases -- Empty inputs, large inputs, invalid inputs
• Use meaningful assertions -- Error messages should help debugging

Architecture Overview

See Architecture for a detailed system overview. Key areas for contribution:

Component	Language	Location
Gateway	Rust	services/gateway/
Storage Engine	Rust	services/storage-engine/
Coordinator	Go	services/coordinator/
Query Engine	Rust	services/query-engine/
Controller	Go	services/controller/
Operator	Go	services/operator/
CLI	Go	tools/cli/
Helm Chart	YAML	deploy/helm/

Recognition

All contributors are:

• Listed in our CONTRIBUTORS.md file
• Thanked in release notes
• Eligible for Thermocline contributor swag

Becoming a Maintainer

Consistent, high-quality contributors may be invited to become maintainers with write access to the repository and voice in project direction.

Community

• GitHub Discussions -- Questions and ideas
• GitHub Issues -- Bug reports and feature requests

License

By contributing to Thermocline, you agree that your contributions will be licensed under the Server Side Public License (SSPL) v1.