Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Contributing

The authoritative contributor guide lives at the repository root, in CONTRIBUTING.md. It is kept there rather than duplicated here so there is one copy to keep current.

This page is a summary and a set of pointers.

The short version

git clone https://github.com/EvilBit-Labs/dbsurveyor.git
cd dbsurveyor
just dev-setup
pre-commit install

just format           # run this BEFORE just check
just check            # format-check, lint, test, vuln -- the gate
just test-integration # container-backed adapter tests (needs Docker)

just check is the gate. Run just format first: the gate starts with a format check, so skipping it turns a whitespace difference into a failure that reads like a lint error.

Before you write code

  1. Read GOTCHAS.md. It records behaviors that have already cost somebody time: tests that reported success over nothing, the asymmetry between how artifacts are written and read, linter rules that contradict each other, and a per-engine list of database quirks re-validated against the current adapters.

  2. Open an issue first. For anything beyond a typo, discuss it before writing code. This saves everyone time if the change does not fit the project’s direction.

  3. One issue per pull request. If a fix needs a refactor, that is a separate pull request, discussed first.

Non-negotiables

Every change must maintain these. They are what the tool exists to promise:

  • Offline only. No network call except to the target database. No telemetry.
  • Read only. No schema modification, no DML, no temporary objects.
  • Credentials never reach output. Not an artifact, not a log line, not an error message.
  • No cgo. A repository test fails on any cgo dependency entering the graph.
  • ASCII only, in source and in Markdown, checked byte by byte.

Several of these are enforced by tests rather than by review, because a reviewer will eventually miss one. See the architecture section of the root guide.

A test that has never failed is not evidence

Before trusting a new invariant test, break the invariant on purpose and watch it fail. Two repository-level tests in this tree reported success over an empty set for months. Both are recorded in GOTCHAS.md section 1, and the pattern is the lesson rather than the two specific bugs.

AI-assisted contributions

Accepted, under the terms in AI_POLICY.md. The short version: you own every line you submit and must be able to explain it, disclose your tools in the pull request, and do not submit output you have not read and run.

Reporting a vulnerability

See SECURITY.md. Do not open a public issue for a security vulnerability.