Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
181 lines (123 loc) · 4.45 KB

CONTRIBUTING.md

File metadata and controls

181 lines (123 loc) · 4.45 KB

Contributing to Filtron

Thank you for your interest in contributing to Filtron! This guide will help you get started with development.

Getting started

Prerequisites

  • Git
  • Bun ≥1.1.0

Initial setup

git clone https://github.com/jbergstroem/filtron.git && cd filtron
bun install # Install dependencies
bun run build # Build all packages
bun test # Test all packages

Code style and correctness

Filtron uses oxlint (including the experimental tsgolint) and oxfmt. Run it all in one go:

bun run lint

Getting help

Development workflow

Making changes

  1. Create a branch

    git switch -c feature/my-feature

  2. Make your changes

    • Edit source files in packages/core/src/ or packages/sql/src/
    • Add or update tests in the respective package
    • Update documentation as needed

  3. Test your changes

    bun test

  4. Build and verify

    bun run build
cd packages/core && bun run examples/basic.ts

  5. Update documentation

    • README.md - Quick start and overview
    • packages/*/README.md - Package-specific documentation
    • CONTRIBUTING.md - Development guide
    • CLAUDE.md - Agent collaboration guide
    • JSDoc comments - In-code documentation

  6. Commit your changes Follow Conventional Commits and the guidelines below

    git add .
git commit -m "feat: add new feature"

Commit message guidelines

Follow these conventions for all commits:

  • Title length: Maximum 72 characters
  • Body wrapping: Wrap at 100 characters
  • Markdown links: Use reference-style links with references in the git footer

Example commit message:

feat: add support for ILIKE operator in SQL converter

This adds case-insensitive pattern matching support for PostgreSQL
and DuckDB dialects. The implementation uses the ILIKE operator
which is more efficient than LOWER() with LIKE. See the benchmark
results in [PR #123][pr-123] for performance comparison.

Closes: https://github.com/jbergstroem/filtron/issues/122
[pr-123]: https://github.com/jbergstroem/filtron/pull/123

Performance

Running benchmarks

As you make changes, compare the before/after. We also keep tabs on this in CI when you open a PR. If you are creating a new package, also add a benchmark in packages/benchmark, similar to how the other benchmarks are maintained.

# All benchmarks (runs core by default)
bun run bench

# Benchmarks for a specific package
bun run --filter='@filtron/sql' bench

Building

Development build

# Full build (all packages)
bun run build
# Only build one package
bun run build --filter='@filtron/core'

Submitting changes

Before Submitting

Checklist:

  • All tests pass: bun test
  • Code builds: bun run build
  • Types are correct: bun run lint
  • Linting passes: bun run lint
  • Documentation updated (if API changed)
  • Benchmarks run (if performance-sensitive code changed)
  • Commit messages follow conventions

Releasing

Releases are automated via GitHub Actions when you push a tag matching the package-version pattern (e.g., core-1.2.0, sql-2.0.0).

The publish workflow runs scripts/verify-tag.ts to validate that:

  • The tag format is valid (package-version, e.g., core-1.2.0)
  • The package directory exists
  • The version in package.json matches the tag
  • The version is not already published on npm

If any of these checks fail, the release is aborted.

Cutting a release

  1. Update the package version

    cd packages/core
# Edit package.json and update the version field

  2. Commit the version change

    git add packages/core/package.json
git commit -m "chore: @filtron/core v1.2.0"

  3. Create a release using GitHub Releases

    If you're releasing multiple packages in one release, make sure all tags are added as part of the release procedure.

    Also, mention all package changes in the release notes.

Code of conduct

Be respectful and constructive in all interactions. We're all here to build great software together.

License

By contributing to Filtron, you agree that your contributions will be licensed under the MIT License.