Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
80 lines (58 loc) · 2.49 KB

CONTRIBUTING.md

File metadata and controls

80 lines (58 loc) · 2.49 KB

Contributing

Quick start (recommended)

The Nix flake dev shell is the recommended way to develop tapes. It pins Go 1.25, GCC, Dagger, and configures all required environment variables (CGO_ENABLED, GOEXPERIMENT). This avoids toolchain drift and CGO build warnings on macOS by using Nix-provided GCC instead of Xcode's system clang.

nix develop          # enter the dev shell
direnv allow         # or use direnv for automatic activation
make build-local
./build/tapes local

Quick start (manual)

If you prefer not to use Nix, ensure you have the prerequisites below.

make build-local
./build/tapes local

Contributing a PR

  1. BEFORE you create a PR, search for existing issues. If no issue exists, create an issue and signal that you'd like to work on it.
  2. When submitting a pull request, ALL titles must be labeled with one of:
  • ⚠️ breaking:- :warning: feat: - adds a breaking change. Triggers a major version bump (i.e., 1.0.0 --> 2.0.0).
  • ✨ feat: - :sparkles: feat: - adds a new feature. Triggers a minor version bump (i.e., 0.1.0 --> 0.2.0).
  • 🔧 fix: - :wrench: fix: - fixes a bug. Triggers a patch bump (i.e., 0.0.1 --> 0.0.2).
  • 🧹 chore: - :broom: chore - non-feature, non-bug code changes (i.e., CICD, tests, etc.). Does NOT trigger a version change.
  • 📚 docs: - :books: docs: - documentation only changes. Does NOT trigger a version change.

Local demo data

Seed demo sessions for the deck UI through the local API server:

tapes deck --demo --api-target http://localhost:8081

To reset demo data, use a fresh database behind the API server.

Prerequisites checklist

  • Go 1.25+
  • Docker (required for make format, make check, make unit-test via Dagger)
  • PostgreSQL with pgvector + pg_duckdb for local runtime work
  • Optional: Ollama for embeddings when running tapes serve

Common issues

  • Merkle hashing requires GOEXPERIMENT=jsonv2
    • make build-local sets this automatically
  • make format/make check/make unit-test require Docker for Dagger
  • Demo seeding docs
    • Use tapes deck --demo --api-target http://localhost:8081 to seed demo sessions
    • Use a fresh Postgres database behind the API when reseeding

Example commands

# Build local binaries
make build-local

# Start local dependencies
./build/tapes local

# Run the deck UI with demo data
./build/tapes deck --demo --api-target http://localhost:8081

# Run tests
make unit-test

# Format code
make format