8000 minigraf/CONTRIBUTING.md at main · project-minigraf/minigraf · GitHub
[go: up one dir, main page]
Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
134 lines (92 loc) · 6.2 KB

CONTRIBUTING.md

File metadata and controls

134 lines (92 loc) · 6.2 KB
Raw

Contributing to Minigraf

Thank you for your interest in contributing. Minigraf is a solo-maintained project with a long-term vision — quality and correctness matter more than pace. Please read this document before opening an issue or pull request.

Before You Contribute

  1. Read PHILOSOPHY.md — understand the core principles before proposing anything. A well-intentioned feature that violates the philosophy (e.g., adds client-server architecture, breaks single-file storage, or adds heavy dependencies) will not be merged.

  2. Read ROADMAP.md — check whether your idea is already planned, deferred, or explicitly out of scope.

  3. Open an issue first for non-trivial changes — a quick discussion before writing code avoids wasted effort.

What We Welcome

  • Bug fixes (with a test that reproduces the bug)
  • Performance improvements with benchmarks showing the gain
  • Documentation improvements and example additions
  • Test coverage improvements (especially error-path cove 7030 rage)
  • Cross-platform compatibility fixes (Linux, macOS, Windows, WASM, mobile, language bindings)

What We Will Not Merge

  • Features that break the single-file storage philosophy
  • Client-server architecture or network protocols in core
  • Large dependency additions that increase binary size significantly
  • Breaking changes to the public API or .graph file format without overwhelming justification
  • Code without tests
  • Features only useful for distributed or enterprise systems

Development Setup

# Clone and build
git clone https://github.com/project-minigraf/minigraf.git
cd minigraf
cargo build

# Run all tests
cargo test

# Run a specific test suite
cargo test --test bitemporal_test -- --nocapture
cargo test --test wal_test -- --nocapture

# Run clippy (must be clean before submitting a PR)
cargo clippy -- -D warnings

# Run the interactive REPL
cargo run

# Try the recursive rules demo
cargo run < demos/demo_recursive.txt

Measuring Code Coverage

Install cargo-llvm-cov (one-time):

cargo install cargo-llvm-cov

Run branch coverage and open the HTML report:

cargo llvm-cov --branch --open

Run branch coverage to check overall project health before submitting a PR.

Code Standards

  • No unsafe code — the crate enforces #![forbid(unsafe_code)]; do not attempt to work around this
  • No unwrap() or expect() in library code paths — use ? and typed errors; unwrap/expect are only acceptable in tests and the binary
  • Every new feature needs tests — unit tests in the relevant src/ module plus integration tests in tests/ where applicable
  • Clippy must pass — cargo clippy -- -D warnings must be clean
  • Format your code — cargo fmt before committing
  • Error paths matter — test failure cases, not just happy paths

Pull Request Process

  1. Fork the repository and create a feature branch from main
  2. Write tests for your change before or alongside the implementation
  3. Ensure cargo test, cargo clippy -- -D warnings, and cargo fmt --check all pass
  4. Update CHANGELOG.md with a brief description of your change under an Unreleased section
  5. Open a PR with a clear description of what the change does and why
  6. Reference any related issues in the PR description

Known Issues and Data-Integrity Bugs

Bugs that can lose, corrupt or hide data are handled so that users can always see them before they adopt a release:

  • An issue labelled data-integrity, corruption or durability stays open until its fix is in a published release, not just merged. The closing comment links that release. A fix merged only to a development branch (such as v3) does not close the issue.
  • Every such bug that affects a published release also gets the known-issue label and an entry in the pinned Known issues in the current release issue: affected versions, symptom, workaround and fix version. The entry is removed when the fix ships.
  • For bugs found downstream, the issue title or body states the affected version range (for example, "v0.6.0 – v2.0.1").
  • The README links to the pinned issue from its "Known issues" section.

At release time, the maintainer updates the pinned issue and closes the issues whose fixes are in the release.

Golden Files

tests/golden/ holds database files written by released versions, each with a manifest of the results it must give (#391). See tests/golden/README.md.

  • Golden files are never regenerated, only added. CI fails a pull request that modifies, deletes or renames one.
  • Every release that changes on-disk behavior (a new format version, a new page or WAL shape, a migration) adds golden files for it, with the recipe in a generator crate under tests/golden/gen/.

Philosophy Check

Before submitting, ask yourself:

  • Does this keep the single-file philosophy intact?
  • Does this maintain zero-configuration?
  • Does this add unnecessary complexity?
  • Is this needed for embedded use cases (mobile, WASM, desktop)?
  • Does this compromise reliability or crash safety?

If you answer "yes" to the last two questions, reconsider. If in doubt, open an issue and discuss first.

Release Process

Releases are managed by the project maintainer. The process is documented in issue #133 and the docs/superpowers/specs/ design files. For each release:

  1. All prerequisite issue PRs merged and CI green
  2. Version bumped consistently across all manifests (Cargo.toml, package.json, pyproject.toml, build.gradle.kts, Package.swift)
  3. cargo check --workspace passes cleanly
  4. All affected docs synced (see CLAUDE.md — "Keep documentation synchronized")
  5. Tag pushed — CI publishes to crates.io, PyPI, npm, and Maven Central automatically
  6. Tier 1 bindings (Python) released alongside the core release; Tier 2 bindings follow on a best-effort schedule (see support tiers)
  7. Known-issues issue updated, and data-integrity/corruption/durability issues fixed by this release closed with a link to it (see above)

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you agree to uphold it.
0