Contributing
Dev workflow
bocal is written in Rust. The pre-push checks (also enforced in CI on Ubuntu + macOS):
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
Or via the Makefile:
make check # fmt + clippy + test
Tests
-
Fast suite (
make test/cargo test) — unit tests plus CLI integration tests that drive the built binary in temp dirs using thecustomengine. No external services. -
Live-service suite (
make e2e) — real Postgres/MySQL round-trips and a real S3 push/pull (incl. multipart) against MinIO, gated behind thedocker_e2efeature so the fast suite never needs Docker:make e2e-up # docker compose: postgres + mysql + minio make e2e # cargo test --features docker_e2e make e2e-down
CI runs both suites on every push/PR.
Conventions
- One logical change per commit.
- A bug fix gets a failing-then-passing test.
- New engines require a unit test for param resolution; a round-trip integration test is the bar for merge.
Contributing a new engine
bocal ships postgres and mysql as built-ins; everything else is reachable today via the custom engine. Promote a custom recipe to a built-in only when it clears the bar: the engine is widely used, its dump/restore is stable across versions, and its tooling is something users already have installed.
The flow — open an issue first, then implement:
-
Open an issue describing the engine and the exact
save/restorecommands you'd run by hand. Maintainers confirm it clears the bar before you write code. -
Implement the
Enginetrait in a new file undersrc/engines/(e.g.src/engines/mongodb.rs). The trait — the same contract the built-in engines satisfy:#![allow(unused)] fn main() { pub trait Engine { fn name(&self) -> &'static str; // the engine = "..." identifier fn dump_file(&self) -> &str; // default dump filename in the tag dir fn save(&self, ctx: &EngineContext) -> Result<()>; fn restore(&self, ctx: &EngineContext) -> Result<()>; fn probe_version(&self, ctx: &EngineContext) -> Result<Option<String>> { Ok(None) } fn probe_client_version(&self, ctx: &EngineContext) -> Result<Option<String>> { Ok(None) } fn check_target(&self, ctx: &EngineContext) -> Result<()> { Ok(()) } fn required_tools(&self, ctx: &EngineContext) -> Vec<String> { Vec::new() } } }EngineContextcarries the resolved host/port, user/dbname resolution (flags → env → defaults, same pattern as postgres/mysql), the tag directory, and the fixture name/tag. -
Register it in
engines::for_service()soengine = "<name>"resolves. -
Document it — add a subsection to Engines with the exact
save/restorecommands and the params it resolves. -
Test — a unit test for param resolution, and a round-trip integration test (save → wipe → restore → assert). Gate live-service tests behind the
docker_e2efeature like the existing ones.
Guidance
Prefer streaming over the wire (e.g. mongodump --archive | gzip) over reading files off a container's disk — it works identically whether the service runs on the host or in Docker, needs no service restart, and keeps the "bocal does not manage services" boundary intact.