Merge nucleic/sleek-thistle-egret-fyej into dev

docs/how-to/README.md

@@ -0,0 +1,8 @@
+# How-to guides
+
+* [How to build](build.md)
+* [How to run tests](run-tests.md)
+* [How to run benchmarks](run-benchmarks.md)
+* [How to release](release.md)
+* [How to upgrade the MSRV](upgrade-msrv.md)
+* [How to record "tapes"](record-tapes.md)

docs/how-to/build.md

@@ -0,0 +1,5 @@
+# How to build and run
+
+1. Install Rust toolchain. We recommend using [rustup](https://rustup.rs/).
+1. Build `brush`: `cargo build`
+1. Run `brush`: `cargo run`

docs/how-to/record-tapes.md

@@ -0,0 +1,16 @@
+# How to record "tapes"
+
+Under the `docs/demos` directory of this repo, we have some `.tape` files checked in.
+These are interactive scripts for recording screencast-style demos of `brush` using
+the [`VHS` tool](https://github.com/charmbracelet/vhs).
+
+## Install `vhs`
+
+You first need to install `vhs`. For consistency, we've found it easiest to install
+`golang` and then follow the instructions on the `vhs` github page to install via
+`go install`. (Also note that there are some native prerequisites required.)
+
+## Run `vhs`
+
+To run `vhs` against the `.tape` file you may need to use `VHS_NO_SANDBOX=1`. For more
+details see [this issue on GitHub](https://github.com/charmbracelet/vhs/issues/504).

docs/how-to/release.md

@@ -0,0 +1,14 @@
+# How to release
+
+_(This is only relevant for project maintainers.)_
+
+* Install [release-plz](https://github.com/MarcoIeni/release-plz)
+* Checkout the `main` branch (with a clean working tree).
+* Run: `release-plz update`. Review its changes, notable including the changelog updates.
+* PR through any generated changes with a `chore: prepare release` commit summary.
+* After the changes have merged into `main`, update your local `main` branch.
+* Acquire GitHub and `crates.io` tokens that have sufficient permissions to publish.
+* Authenticate with `crates.io` by running: `cargo login`.
+* Run: `release-plz release --backend github --git-token <TOKEN>`.
+* Update the published GitHub release to include an auto-generated changelog.
+* Run: `cargo install --locked brush-shell` to verify the release.

docs/how-to/run-benchmarks.md

@@ -0,0 +1,31 @@
+# How to run benchmarks
+
+## Using xtask (Recommended)
+
+The project provides `cargo xtask` commands for running benchmarks:
+
+```bash
+# Run benchmarks
+cargo xtask analyze bench
+
+# Run benchmarks and save output to a file
+cargo xtask analyze bench --output benchmarks.txt
+```
+
+## Manual Approach (Alternate)
+
+To run performance benchmarks:
+
+```bash
+cargo bench --workspace --benches
+```
+
+## Collecting flamegraphs
+
+To collect flamegraphs from performance benchmarks (running for 10 seconds):
+
+```bash
+cargo bench --workspace --benches -- --profile-time 10
+```
+
+The flamegraphs will be created as `.svg` files and placed under `target/criterion/<benchmark_name>/profile`.

docs/how-to/run-tests.md

@@ -0,0 +1,48 @@
+# How to run tests
+
+## Using xtask (Recommended)
+
+The project provides `cargo xtask` commands for running tests:
+
+```bash
+# Run unit tests (fast tests excluding integration binaries)
+cargo xtask test unit
+
+# Run integration tests (all workspace tests including compat tests)
+cargo xtask test integration
+
+# Run tests with code coverage
+cargo xtask test integration --coverage --coverage-output codecov.xml
+```
+
+## CI Workflows
+
+For comprehensive validation, use the CI workflows:
+
+```bash
+# Quick inner-loop checks (~7s warm): fmt, build, lint, unit tests
+cargo xtask ci quick
+
+# Full pre-commit checks (~45s warm): quick + deps, schemas, integration tests
+cargo xtask ci pre-commit
+```
+
+## Manual Approach (Alternate)
+
+To run all workspace tests:
+
+```bash
+cargo test --workspace
+```
+
+To run just bash compatibility tests:
+
+```bash
+cargo test --test brush-compat-tests
+```
+
+To run a specific compatibility test case
+
+```bash
+cargo test --test brush-compat-tests -- '<name of test case>'
+```

docs/how-to/upgrade-msrv.md

@@ -0,0 +1,69 @@
+# How to upgrade MSRV
+
+This document outlines the process for upgrading the Minimum Supported Rust Version (MSRV) for the `brush` project.
+
+## Overview
+
+Before upgrading MSRV, review the [MSRV Policy](../reference/msrv-policy.md) to ensure the update aligns with project guidelines.
+
+## Process
+
+### 1. Find all MSRV references
+
+Search for the current MSRV version throughout the codebase:
+
+```bash
+grep -r "<current-version>" .
+```
+
+Typically, MSRV is specified in:
+- `Cargo.toml` (workspace `rust-version` field)
+- `.github/workflows/ci.yaml` (CI test matrix)
+- `.github/copilot-instructions.md` (GitHub Copilot instructions)
+
+### 2. Update MSRV references
+
+Update all occurrences to the new version:
+
+- **`Cargo.toml`**: Update the `rust-version` field under `[workspace.package]`
+- **`.github/workflows/ci.yaml`**: Update the version in the test matrix
+
+### 3. Verify the build
+
+Test that the project builds successfully with the updated MSRV:
+
+```bash
+cargo check --workspace
+```
+
+### 4. Run tests
+
+Verify that tests pass with the new MSRV:
+
+```bash
+cargo test --workspace
+```
+
+### 5. Run static checks
+
+After upgrading MSRV, it's important to rerun all static checks, as newer Rust versions may introduce new lints and clippy warnings that weren't present in the previous MSRV. These warnings need to be resolved to maintain code quality.
+
+Run clippy with all warnings treated as errors:
+
+```bash
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+Also run other static checks such as formatting:
+
+```bash
+cargo fmt --all -- --check
+```
+
+**Note**: Upgrading MSRV often enables new clippy lints (particularly in nursery categories) that may flag code patterns that were previously acceptable. Review and fix these warnings, as they often suggest improvements like adding `const` to functions or other optimizations that are newly available in the updated Rust version.
+
+### 6. Update documentation
+
+When merging the MSRV update:
+- Call out the update in an appropriate Conventional Commit commit description
+- Include justification for the change in the release notes