Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
190 lines (127 loc) · 7.76 KB

CONTRIBUTING.md

File metadata and controls

190 lines (127 loc) · 7.76 KB
Raw

Contributing to DBFlux

Thanks for considering a contribution. This guide explains how to file issues, open pull requests, and follow the conventions DBFlux uses for releases and labels.

Quick Links

Project Setup

DBFlux is a Rust workspace using GPUI for the UI. The full feature set requires the database driver feature flags:

cargo check --workspace
cargo build
cargo run

On Linux, the mold linker is required for local builds: .cargo/config.toml links the x86_64-unknown-linux-gnu target with -fuse-ld=mold to cut link time and memory across the workspace. Install it via your package manager (e.g. apt install mold); the Nix dev shell provides it automatically. Windows and macOS are unaffected.

Before opening a PR run:

cargo fmt --all -- --check
cargo clippy --workspace -- -D warnings
cargo test --workspace

Tests can also be run with cargo-nextest (faster on this workspace, provided by the Nix dev shell). Note nextest does not run doctests:

cargo nextest run --workspace
cargo test --doc --workspace

A Nix dev shell is available: nix develop.

Branching Model

DBFlux uses trunk-based development with short-lived release branches:

  • main is the only long-lived branch. All work targets main.
  • release/vX.Y branches are cut from main only when a minor needs to be stabilized for a stable release. They accept cherry-picked fixes from main only — no new features.

Contributors should always target main with their PRs. Backporting to a release branch is a maintainer responsibility.

The full rules (tags, version bumps, cut procedure, CHANGELOG discipline) live in docs/RELEASE.md.

Commit Convention

Use Conventional Commits where it fits naturally:

  • feat(scope): … — new user-facing capability
  • fix(scope): … — bug fix
  • refactor(scope): … — internal change with no behavior change
  • perf(scope): … — performance improvement
  • docs(scope): … — documentation only
  • test(scope): … — tests only
  • ci(scope): … — CI / release workflow changes
  • chore(scope): … — repo plumbing (deps, tooling, version bumps)

Scope is the affected area: a driver name (postgres, mongodb), ui, mcp, audit, rpc, release, etc. Keep the subject under 70 chars; explain the why in the body when non-obvious.

Pull Requests

  1. Branch from main. Keep PRs focused on a single concern.
  2. Fill in the PR template: summary, what it resolves, how it was solved, validation evidence, and where it was tested.
  3. Link the issue it closes with Resolves #N in the description.
  4. Apply the labels that describe the change. See Label Guide below.
  5. Keep diffs reviewable. PRs over ~400 changed lines should be split into stacked/chained PRs unless the maintainer approves a size:exception.
  6. CI must pass (tests.yml, style.yml). Re-run locally before pushing if anything fails.

Commit messages are load-bearing

DBFlux uses git-cliff to generate the changelog and release notes directly from git history. Do not hand-edit CHANGELOG.md or [Unreleased]. Your commit message is what surfaces to users.

Rules for what appears in the changelog:

Type Surfaces in changelog?
feat Yes — under Added
fix Yes — under Fixed
perf Yes — under Changed
refactor, test, ci, chore, docs, style, build No — internal only
Any type with (security) scope or Security: footer Yes — under Security

Breaking changes (feat!:, fix!:, or a BREAKING CHANGE: footer) always surface regardless of type.

What this means in practice:

  • User-visible changes must use feat, fix, or perf as the type. A chore or refactor commit is invisible to users in the changelog.
  • Write a clear, imperative subject line — it becomes the changelog bullet verbatim.
  • If a single PR contains both internal and user-visible changes, split them into separate commits with the appropriate types.
  • Security fixes: use fix(security): ... or add a Security: ... trailer so the change lands under the Security section.

Issues

Before opening an issue:

  • Search existing issues to avoid duplicates.
  • Reproduce against a recent build if you can.

Include:

  • Version of DBFlux (dbflux --version), OS / display server (X11 vs Wayland on Linux), and database engine + version.
  • Steps to reproduce.
  • Expected vs actual behavior.
  • Logs if relevant. Redact secrets.

Apply the labels that describe the issue. See Label Guide.

Label Guide

The repo uses a structured label taxonomy. Apply one label from each applicable axis when opening an issue or PR. Maintainers may adjust during triage.

Kind (one of *:bug or *:feature per affected area)

Areas that have a bug/feature split:

Area Bug Feature
AWS aws:bug aws:feature
Audit audit:bug audit:feature
Driver driver:bug driver:feature
MCP mcp:bug mcp:feature
Pipeline pipeline:bug pipeline:feature
Proxy proxy:bug proxy:feature
Query query:bug query:feature
RPC rpc:bug rpc:feature
SSH ssh:bug ssh:feature
Storage storage:bug storage:feature
UI ui:bug ui:feature

Plus the generic GitHub-default bug, documentation, question, help wanted, good first issue, invalid.

Subsystem flags (apply when relevant)

  • aws, proxy, ssh, query, driver, mcp

Driver (when the change is driver-specific)

driver:mongodb, driver:postgres, driver:sqlite, driver:mysql/mariadb, driver:dynamodb, driver:redis

Data model kind (for store/driver-level work)

kind:sql, kind:document, kind:kv, kind:log

Platform / Arch (when behavior is platform-specific)

  • Platform: platform:linux, platform:macos, platform:windows
  • Arch: arch:amd64, arch:arm64

RPC subtype (when touching RPC-backed services)

rpc:auth, rpc:driver (in addition to rpc:bug/rpc:feature)

Priority

priority:high, priority:medium, priority:low — usually applied by maintainers during triage.

Status (applied by maintainers)

status:needs-review, status:approved, status:rejected

Example combinations

  • A PostgreSQL JSON query bug on Linux: driver:bug, driver:postgres, query:bug, platform:linux, kind:sql
  • A new Redis pub/sub feature: driver:feature, driver:redis, kind:kv
  • An MCP approval-flow regression on Windows: mcp:bug, platform:windows
  • An SSH tunnel UI improvement: ui:feature, ssh:feature, ssh

If you're unsure, label as best you can — maintainers will refine during triage.

Security

Do not file security issues publicly. Email the maintainer or use a private channel. Logs and reproductions must be redacted of secrets (tokens, passwords, connection strings).

License

By contributing you agree your contributions are licensed under the project's dual MIT / Apache-2.0 license.