Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
109 lines (87 loc) · 4.35 KB

CONTRIBUTING.md

File metadata and controls

109 lines (87 loc) · 4.35 KB
Raw

Contributing to git-remote-object-store

Thanks for considering a contribution. This document covers the essentials. Project conventions live under AGENTS.md and the rule files in .claude/rules/ — start there before making a non-trivial change.

Ground rules

  • By submitting a pull request, you agree to license your contribution under the project's license, Apache-2.0 (see LICENSE).
  • Security-sensitive reports must not go in public issues — see SECURITY.md for the private reporting flow.

Getting started

git clone https://github.com/dekobon/git-remote-object-store
cd git-remote-object-store
cargo build --workspace
cargo test --workspace

MSRV is declared in the workspace Cargo.toml (rust-version). The current floor is Rust 1.94.

The repository ships a Makefile that mirrors CI:

make ci          # everything CI runs (fmt, clippy, lints, tests, shellspec)
make check-tools # verify your local toolchain matches what CI expects

For backend-touching changes, the Docker-backed integration suites exercise real S3 (RustFS) and Azure Blob (Azurite) emulators:

cargo test --features integration-s3 --test s3_store_integration
cargo test --features integration-azure --test azure_store_integration

Optional CLI prerequisites for the spec/ ShellSpec suite: ShellSpec (the install script lives in make ci, but you can also install manually).

Project conventions

The canonical reference is AGENTS.md plus the per-topic files in .claude/rules/:

Topic File
Rust style .claude/rules/rust.md
Naming .claude/rules/naming.md
Testing .claude/rules/testing.md
Conventional commits .claude/rules/git-commits.md
Tool choice (LSP-first) .claude/rules/tool-choice.md
Bash style .claude/rules/bash.md
Markdown .claude/rules/markdown.md
Helper-binary stdout discipline .claude/rules/protocol-stdout.md
Changelog .claude/rules/changelog.md
Documentation hygiene .claude/rules/documentation.md

Highlights:

  • Rust style: cargo fmt, clippy clean with --all-targets --all-features -- -D warnings. No unsafe code. Avoid unwrap / expect / panic! outside tests.
  • Commits: Conventional Commits — <type>(<scope>): <subject>. Validated in CI by commitsar.
  • Tests: add a regression test whenever you fix a bug. Assertions must be specific (not is_ok() without checking the value). See .claude/rules/testing.md for the full discipline including the "no incidental coupling" rule.
  • Helper-binary stdout is a contract: the git-remote-* and git-lfs-* binaries communicate with git over a line-based protocol on stdout. Diagnostic output goes to stderr only — never println!, dbg!, or stray banner text on stdout outside protocol responses.
  • Docs: /// on public items; the crate warns on missing_docs.

Workflow

  1. Open an issue first for anything beyond a trivial fix. It's cheaper to discuss the design than to review a large PR against the grain of the project.
  2. Branch from main.
  3. Commit in small, reviewable steps. Each commit should build and pass tests on its own where practical.
  4. Run make ci before pushing.
  5. Open a pull request against main. Fill in the PR template. Link the issue with Fixes #NNN in the PR body.
  6. Changelog: add an entry to CHANGELOG.md under [Unreleased] for user-visible changes. Refactors, docs-only, and CI-only changes don't need a changelog entry.

Code review

Criticism is welcome — point out mistakes, suggest better approaches, cite relevant standards. Be skeptical and concise. Reviews focus on correctness, API shape, and test coverage before style.

Questions

Open a GitHub Discussion or a low-priority issue. We'd rather answer a question than review a PR that went the wrong direction.