Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
96 lines (72 loc) · 2.97 KB

CONTRIBUTING.md

File metadata and controls

96 lines (72 loc) · 2.97 KB

Contributing

Quick start (recommended)

The Nix flake dev shell is the recommended way to develop tapes. It pins Go 1.25, GCC, Dagger, SQLite dev headers, 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 deck --demo

Quick start (manual)

If you prefer not to use Nix, ensure you have the prerequisites below and note that you may see harmless deprecation warnings from Apple's SDK headers during CGO compilation.

make build-local
./build/tapes deck --demo

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 without touching real data:

tapes deck -m
tapes deck --demo --sqlite ./tapes.demo.sqlite

To reset the demo database:

tapes deck -m -f

Prerequisites checklist

  • Go 1.25+
  • CGO enabled and SQLite dev libraries (e.g., libsqlite3)
  • Docker (required for make format, make check, make unit-test via Dagger)
  • Optional: Ollama for embeddings when running tapes serve

Common issues

  • SQLite deprecation warnings on macOS (e.g., sqlite3_auto_extension is deprecated)
    • These are harmless warnings from Apple's SDK headers. Use the Nix dev shell to avoid them.
  • SQLite errors when building or running
    • Ensure SQLite dev libraries are installed and CGO_ENABLED=1
  • 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 to seed demo sessions
    • Demo DB path defaults to ./tapes.demo.sqlite
    • Reseed with tapes deck --demo --overwrite

Example commands

# Build local binaries
make build-local

# Run the deck UI with demo data
./build/tapes deck --demo

# Reseed demo data
./build/tapes deck --demo --overwrite

# Run tests
make unit-test

# Format code
make format

# Run deck against a specific database
TAPES_SQLITE=./tapes.sqlite ./build/tapes deck