From 2f841ae16f1c25e5623bd5fff38649feb0e55e76 Mon Sep 17 00:00:00 2001
From: "codegen-sh[bot]" <131295404+codegen-sh[bot]@users.noreply.github.com>
Date: Sun, 22 Jun 2025 23:45:34 +0000
Subject: [PATCH] docs: update README and CONTRIBUTING to reflect hk and mise
 workflow

- Add mise as recommended task runner and tool manager
- Document hk git hooks for automated code quality checks
- Update development setup instructions to use mise install
- Add comprehensive tool workflow documentation
- Update testing instructions to use mise/hk commands
- Modernize pre-submission checklist to reflect automated hooks
- Add quick reference for available mise tasks and hk hooks
- Maintain backward compatibility with manual setup instructions
---
 CONTRIBUTING.md | 147 ++++++++++++++++++++++++++++++++++++++++--------
 README.md       | 128 ++++++++++++++++++++++++++++++++++-------
 2 files changed, 230 insertions(+), 45 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 27acca8..a411dc3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -62,39 +62,127 @@ cd submod
 git remote add upstream https://github.com/originaluser/submod.git
 ```
 
-### 2. Install Dependencies
+### 2. Install Mise and Dependencies
 
 ```bash
-# Using Mise (recommended for consistent environment)
+# Install mise (if you haven't already)
+curl https://mise.run | sh
+
+# Install all development tools and dependencies
 mise install
 
-# Or install Rust manually
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+# This automatically installs:
+# - Rust 1.87+
+# - hk (git hooks)
+# - cargo tools (nextest, audit, deny, watch)
+# - prettier, typos, and other linters
 ```
 
 ### 3. Verify Setup
 
 ```bash
 # Build the project
-cargo build
+mise run build
 
 # Run tests to ensure everything works
-cargo test
+mise run test
 
-# Run the comprehensive test suite
-./scripts/run-tests.sh
+# Run the full CI suite
+mise run ci
+
+# Verify git hooks are installed
+hk --version
+```
+
+### 4. Development Workflow
+
+With mise and hk installed, you have access to streamlined development commands:
+
+```bash
+# Development tasks
+mise run build         # Build the project
+mise run test          # Run tests
+mise run lint          # Run clippy
+mise run ci            # Full CI pipeline
+
+# Git hooks (run automatically on commit)
+hk pre-commit          # Run pre-commit checks manually
+hk fix                 # Auto-fix issues where possible
+hk check               # Run all linters
 ```
 
-### 4. Install Development Tools
+### 5. Manual Setup (Alternative)
+
+If you prefer not to use mise:
 
 ```bash
-# Install useful development tools
+# Install Rust manually
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# Install development tools manually
 cargo install cargo-watch      # Watch for changes
 cargo install cargo-audit      # Security auditing
 cargo install cargo-deny       # Dependency checking
 cargo install cargo-nextest    # Better test runner
+
+# Build and test
+cargo build
+cargo test
+./scripts/run-tests.sh
+```
+
+## 🔧 Development Tools Overview
+
+This project uses modern development tools to streamline the contribution process:
+
+### Mise - Task Runner & Tool Manager
+
+[Mise](https://mise.jdx.dev/) manages our development environment and provides consistent task execution:
+
+```bash
+# Available tasks
+mise run build         # Build the project (alias: mise run b)
+mise run test          # Run the test suite
+mise run lint          # Run clippy linting
+mise run ci            # Full CI pipeline (build + lint + test)
+mise run clean         # Clean build artifacts
+mise run release       # Cut a new release (maintainers only)
+```
+
+### hk - Git Hooks Manager
+
+[hk](https://github.com/jdx/hk) provides automated git hooks for code quality:
+
+```bash
+# Hook commands
+hk pre-commit          # Run pre-commit checks
+hk pre-push            # Run pre-push checks  
+hk check               # Run all linters
+hk fix                 # Auto-fix issues where possible
+hk test                # Run tests only
+hk ci                  # Run CI checks
 ```
 
+### Automated Quality Checks
+
+The pre-commit hooks automatically run these tools on every commit:
+
+- **cargo fmt** - Formats Rust code
+- **cargo clippy** - Lints Rust code for common issues
+- **cargo test** - Runs the test suite (with nextest for parallel execution)
+- **typos** - Checks for spelling errors in code and documentation
+- **prettier** - Formats TOML, YAML, and other configuration files
+- **cargo deny** - Audits dependencies for security vulnerabilities and license compliance
+- **pkl** - Validates pkl configuration files
+
+### Tool Integration
+
+Both tools work together seamlessly:
+- **mise** handles tool installation and version management
+- **hk** uses the tools installed by mise for git hooks
+- Both can run the same underlying commands (e.g., `mise run test` and `hk test`)
+- CI uses the same tools for consistency between local and remote environments
+
 ## 🔄 Making Changes
 
 ### 1. Create a Branch
@@ -168,17 +256,22 @@ My philosophy on testing is to "test what matters." Tests focus on integration a
 ### Running All Tests
 
 ```bash
-# Quick test run
-cargo test
-
-# Comprehensive test suite with reporting
-./scripts/run-tests.sh --verbose
-
-# Include performance tests
-./scripts/run-tests.sh --performance
-
-# Filter specific tests
-./scripts/run-tests.sh --filter sparse_checkout
+# Using mise (recommended)
+mise run test           # Quick test run
+mise run ci             # Full CI suite (build + lint + test)
+
+# Using hk
+hk test                 # Run tests only
+hk ci                   # Run CI checks
+hk check                # Run all linters and checks
+
+# Using cargo directly
+cargo test              # Quick test run
+
+# Using the test script
+./scripts/run-tests.sh --verbose     # Comprehensive test suite with reporting
+./scripts/run-tests.sh --performance # Include performance tests
+./scripts/run-tests.sh --filter sparse_checkout  # Filter specific tests
 ```
 
 ### Writing Tests
@@ -235,13 +328,19 @@ fn test_submod_init_command() {
 Before submitting your PR, ensure:
 
 - [ ] **Code compiles** without warnings
-- [ ] **All tests pass** (`./scripts/run-tests.sh`)
-- [ ] **Code is formatted** (`cargo fmt`)
-- [ ] **Lints pass** (`cargo clippy`)
+- [ ] **All tests pass** (`mise run ci` or `hk ci`)
+- [ ] **Pre-commit hooks pass** (automatically run on commit, or manually with `hk pre-commit`)
 - [ ] **Documentation is updated** if needed
 - [ ] **CHANGELOG is updated** for user-facing changes
 - [ ] **Commit messages follow conventions**
 
+**Note**: If you're using the recommended mise/hk setup, many checks are automated:
+- **Code formatting** (`cargo fmt`) - Auto-fixed by pre-commit hooks
+- **Linting** (`cargo clippy`) - Checked by pre-commit hooks  
+- **Spell checking** (`typos`) - Checked and auto-fixed by pre-commit hooks
+- **TOML/YAML formatting** (`prettier`) - Auto-fixed by pre-commit hooks
+- **Security auditing** (`cargo deny`) - Checked by pre-commit hooks
+
 ### 2. Submitting the PR
 
 ```bash
diff --git a/README.md b/README.md
index 0e4b3a2..089ab59 100644
--- a/README.md
+++ b/README.md
@@ -239,14 +239,95 @@ submod sync
 
 - Rust 1.87 or later
 - Git
+- [Mise](https://mise.jdx.dev/) (recommended) - for tool management and task running
 
-### Building from Source
+### Quick Setup with Mise (Recommended)
 
 ```bash
 # Clone the repository
 git clone https://github.com/bashandbone/submod.git
 cd submod
 
+# Install mise if you haven't already
+curl https://mise.run | sh
+
+# Install all development tools and dependencies
+mise install
+
+# Build the project
+mise run build
+# or: mise run b (alias)
+
+# Run tests
+mise run test
+
+# Run the full CI suite (build + lint + test)
+mise run ci
+```
+
+### Available Mise Tasks
+
+```bash
+# Build the project
+mise run build          # or: mise run b
+
+# Run tests
+mise run test
+
+# Lint with clippy
+mise run lint
+
+# Run full CI pipeline
+mise run ci
+
+# Clean build artifacts
+mise run clean
+
+# Cut a new release (maintainers only)
+mise run release
+```
+
+### Git Hooks with hk
+
+This project uses [hk](https://github.com/jdx/hk) for automated git hooks that ensure code quality:
+
+```bash
+# Install git hooks (done automatically with mise install)
+hk install
+
+# Run pre-commit checks manually
+hk pre-commit
+
+# Run all linters and checks
+hk check
+
+# Auto-fix issues where possible
+hk fix
+
+# Run CI checks locally
+hk ci
+```
+
+The pre-commit hooks automatically run:
+- **cargo fmt** - Code formatting
+- **cargo clippy** - Linting
+- **cargo test** - Test suite
+- **typos** - Spell checking
+- **prettier** - TOML/YAML formatting
+- **cargo deny** - Security and license auditing
+
+### Manual Setup (Alternative)
+
+If you prefer not to use mise:
+
+```bash
+# Clone the repository
+git clone https://github.com/bashandbone/submod.git
+cd submod
+
+# Install Rust if needed
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
 # Build the project
 cargo build
 
@@ -260,20 +341,22 @@ cargo test
 ### Running Tests
 
 ```bash
-# Run all tests
-cargo test
-
-# Run integration tests only
-cargo test --test integration_tests
-
-# Run with the test script for better reporting
-./scripts/run-tests.sh
-
-# Run performance tests
-./scripts/run-tests.sh --performance
-
-# Filter specific tests
-./scripts/run-tests.sh --filter sparse_checkout
+# Using mise (recommended)
+mise run test           # Run all tests
+mise run ci             # Run full CI suite
+
+# Using hk
+hk test                 # Run tests only
+hk ci                   # Run CI checks
+
+# Using cargo directly
+cargo test              # Run all tests
+cargo test --test integration_tests  # Integration tests only
+
+# Using the test script
+./scripts/run-tests.sh --verbose     # Comprehensive reporting
+./scripts/run-tests.sh --performance # Include performance tests
+./scripts/run-tests.sh --filter sparse_checkout  # Filter tests
 ```
 
 ### Project Structure
@@ -299,11 +382,12 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 
 1. **Fork the repository**
 2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
-3. **Make your changes** and add tests if applicable (test anything that has a result)
-4. **Run the test suite**: `./scripts/run-tests.sh`
-5. **Commit your changes**: `git commit -m 'Add amazing feature'`
-6. **Push to your branch**: `git push origin feature/amazing-feature`
-7. **Open a Pull Request**
+3. **Set up development environment**: `mise install` (installs all tools and git hooks)
+4. **Make your changes** and add tests if applicable
+5. **Run the test suite**: `mise run ci` (or `hk ci`)
+6. **Commit your changes**: `git commit -m 'Add amazing feature'` (hooks run automatically)
+7. **Push to your branch**: `git push origin feature/amazing-feature`
+8. **Open a Pull Request**
 
 ### Development Guidelines
 
@@ -311,7 +395,9 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 - Add tests for new functionality. I'm not big on unit tests, but integration tests are essential.
 - Update documentation for user-facing changes
 - Use conventional commit messages
-- Ensure all tests pass before submitting PR
+- Run `mise run ci` or `hk ci` before submitting PR
+- Pre-commit hooks will automatically format code and run basic checks
+- All automated checks must pass before PR can be merged
 
 ## 🔍 Troubleshooting