Skip to content

Latest commit

 

History

History
111 lines (78 loc) · 3.07 KB

DEV.md

File metadata and controls

111 lines (78 loc) · 3.07 KB

Development Guide

Prerequisites

Building

just build      # Debug build (alias: b)
just release    # Release build (alias: r)

Testing

just test           # Run all tests (alias: t)
just test-verbose   # Run tests with output shown (alias: tv)
just test <name>    # Run specific test (via cargo test)

Run a single test directly:

cargo test <test_name>
cargo test apply::applies_single_file  # Run specific test module::test_name

Test Organization

  • tests/cli.rs - CLI integration tests using assert_cmd
  • tests/common/mod.rs - Shared test utilities and fixtures
  • src/testutil.rs - Test helper module with create_test_repo() / create_test_overlay()
  • Unit tests - Embedded within individual modules (lib.rs, state.rs, etc.)

Tests create temporary git repos using tempfile::TempDir. Some tests require serial execution due to environment variable handling (coverage runs use --test-threads=1).

Linting and Formatting

Clippy is configured with pedantic and nursery lints enabled.

just lint       # Run clippy (alias: l)
just format     # Format code (aliases: fmt, f)
just fmt-check  # Check formatting without changes (alias: fc)
just check      # Run format check, lint, and tests (alias: c)

Running Locally

just run apply ./test-overlay
just run status
just run --help

Or install locally:

just install    # alias: i
repoverlay --help

Additional Commands

just clean          # Clean build artifacts
just watch-test     # Watch mode for tests (alias: wt)
just watch-lint     # Watch mode for clippy (alias: wl)
just test-coverage  # Run tests with coverage (alias: tc)
just coverage-html  # Generate HTML coverage report
just coverage-report # Open coverage report in browser
just audit          # Run security audit with cargo-audit and cargo-deny (alias: a)
just docs           # Build documentation (alias: d)

CI

The CI workflow runs on pull requests and pushes to main:

just ci   # Runs: test, lint, fmt-check

Release Process

Releases are automated via release-plz:

  1. Automatic PR: When commits are pushed to main, release-plz creates/updates a release PR with version bumps and changelog updates.

  2. Merge to release: Merging the release PR creates a git tag (v<version>).

  3. Publish: The tag triggers the release workflow which:

    • Publishes to crates.io
    • Creates a GitHub release with auto-generated notes

Manual Version Bumps

release-plz determines version bumps from conventional commit messages:

  • fix: - Patch version bump
  • feat: - Minor version bump
  • feat!: or BREAKING CHANGE: - Major version bump

Required Secrets

  • CARGO_REGISTRY_TOKEN - For publishing to crates.io

Project Structure

See ARCHITECTURE.md for detailed module structure and responsibilities.