Contributing Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides technical instructions and standards for contributing to the chkpt project. chkpt is a fast, content-addressable checkpoint system designed for saving and restoring workspace snapshots using XXH3-128 hashing and LZ4 compression.
Contributors can engage with the project by reporting bugs, suggesting enhancements, or submitting pull requests across various components, including the core Rust library, CLI, MCP server, and Node.js bindings.
Sources: README.md:1-10, CLAUDE.md:5-10, CONTRIBUTING.md:1-5
Development Workflow
The project follows a standard fork-and-pull request model. Contributors should create feature branches from main and ensure all changes adhere to the established style guidelines and pass the comprehensive test suite.
Pull Request Process
- Fork the repository and create a branch:
git checkout -b feature/your-feature. - Implement changes following the Code Style guidelines.
- Ensure the project builds and all tests pass.
- Open a pull request with a clear description and reference relevant issues.
Sources: CONTRIBUTING.md:20-28
Branching and Contribution Flow
The following diagram illustrates the lifecycle of a contribution from reporting to merging.
A visual representation of the contribution pipeline.
Sources: CONTRIBUTING.md:7-28, CLAUDE.md:46-51
Project Architecture and Layout
chkpt is organized as a Cargo workspace with specialized crates for different interfaces and core logic.
| Crate | Path | Description |
|---|---|---|
chkpt-core | crates/chkpt-core/ | Core library: scanner, store (blob/tree/pack), index, and ops. |
chkpt-cli | crates/chkpt-cli/ | Command-line interface using clap and dialoguer. |
chkpt-mcp | crates/chkpt-mcp/ | MCP server implementing rmcp with stdio transport. |
chkpt-napi | crates/chkpt-napi/ | Node.js native bindings using NAPI-RS. |
chkpt-plugin | crates/chkpt-plugin/ | Claude Code plugin containing MCP tools and skills. |
Sources: CLAUDE.md:12-20, README.md:85-92
Store Layout
The system stores data in a deterministic path based on the workspace path hash.
The storage structure managed by the StoreLayout module.
Sources: crates/chkpt-core/src/config.rs:17-60, README.md:75-83
Technical Environment Setup
Rust Development
The project uses the Rust 2021 edition.
# Clone and build
git clone https://github.com/syi0808/chkpt.git
cd chkpt
cargo build
cargo test --workspace
Sources: CONTRIBUTING.md:32-37, CLAUDE.md:38-40
Node.js Bindings Development
Development for chkpt-napi requires pnpm and specific build tools for cross-compilation.
cd crates/chkpt-napi
pnpm install
pnpm build
pnpm test
Sources: CONTRIBUTING.md:41-45, crates/chkpt-napi/package.json:20-25
Standards and Conventions
Code Style
- Error Handling: Use
thiserrorfor library crates (chkpt-core) andanyhowfor binary crates (chkpt-cli,chkpt-mcp). - Async: Use the
tokioruntime. - Serialization:
serdewithbincodefor tree structures andserde_jsonfor snapshots/config. - Formatting: Always run
cargo fmt --allbefore committing. - Linting: Ensure
cargo clippy --workspacepasses with no warnings.
Sources: CONTRIBUTING.md:55-63, CLAUDE.md:38-44
Commit Messages
chkpt enforces the Conventional Commits specification.
| Type | Description | Example |
|---|---|---|
feat | A new feature | feat: add dry-run support |
fix | A bug fix | fix: handle symlinks during scan |
docs | Documentation only | docs: update installation instructions |
test | Adding missing tests | test: add index concurrency tests |
Sources: CONTRIBUTING.md:67-75, CLAUDE.md:43-44
Testing Infrastructure
Contributors must run the full suite before submission.
Rust Tests
Tests for major components (blob storage, indexing, scanning) are located in crates/chkpt-core/tests/.
# Run all workspace tests
cargo test --workspace
# Run a specific test
cargo test -p chkpt-core --test blob_test
Sources: CONTRIBUTING.md:81-91, CLAUDE.md:29-35
Node.js Tests
Bindings tests are located in crates/chkpt-napi/__test__/ and use vitest.
cd crates/chkpt-napi
pnpm test
# Run specific test file
pnpm vitest run __test__/ops.spec.ts
Sources: CONTRIBUTING.md:85-96, crates/chkpt-napi/package.json:24
Summary
Contributing to chkpt involves working within a multi-language workspace (Rust/TypeScript) centered around a content-addressable core. By following the Conventional Commits standard, adhering to Rust 2021 conventions, and utilizing the provided testing tools, contributors ensure the stability and performance of the checkpoint system.
Sources: CONTRIBUTING.md:98-100