# Criterion Baseline Workflow

Step-by-step guide for A/B performance comparison using Criterion's baseline feature.

## Prerequisites

Ensure `[dev-dependencies]` includes `criterion` and the library crate:

```toml
[dev-dependencies]
criterion = { workspace = true }
opendeviationbar = { path = "crates/opendeviationbar" }
```

And the benchmark binary is declared:

```toml
[[bench]]
name = "opendeviationbar_bench"
harness = false
```

## Workflow A - Uncommitted Changes (git stash)

Best when optimizations are not yet committed.

```bash
# 1. Verify benchmark compiles with current changes
cargo bench --bench opendeviationbar_bench -- --test

# 2. Stash all changes
git stash push -m "optimization-changes"

# 3. Re-apply ONLY non-functional fixes needed for compilation
#    (e.g., [dev-dependencies], .unwrap() additions)
#    These must NOT affect benchmarked code paths

# 4. Run baseline
cargo bench --bench opendeviationbar_bench -- --save-baseline before

# 5. Restore optimized code
git stash pop

# 6. Run comparison
cargo bench --bench opendeviationbar_bench -- --baseline before

# 7. View HTML report
open target/criterion/report/index.html
```

**Caveat**: If the stash removes non-functional fixes (like dev-deps), you must re-apply them before running the baseline. This is the main complexity of the stash approach.

## Workflow B - Committed Changes (branch checkout)

Best when optimizations are on a feature branch.

```bash
# 1. Save current branch name
BRANCH=$(git branch --show-current)

# 2. Checkout baseline (e.g., main)
git checkout main

# 3. Run baseline
cargo bench --bench opendeviationbar_bench -- --save-baseline before

# 4. Return to feature branch
git checkout $BRANCH

# 5. Run comparison
cargo bench --bench opendeviationbar_bench -- --baseline before

# 6. View HTML report
open target/criterion/report/index.html
```

## Workflow C - Two Named Commits

Best for comparing any two specific points in history.

```bash
# 1. Checkout "before" commit
git checkout <before-sha>
cargo bench --bench opendeviationbar_bench -- --save-baseline before

# 2. Checkout "after" commit
git checkout <after-sha>
cargo bench --bench opendeviationbar_bench -- --baseline before
```

## Thermal Validation (Gold Standard)

Run the comparison in REVERSE order to rule out thermal effects:

```bash
# Run "after" first (when CPU is cold)
cargo bench --bench opendeviationbar_bench -- --save-baseline after-first

# Then run "before"
git stash push -m "temp" && <apply-fixes>
cargo bench --bench opendeviationbar_bench -- --baseline after-first
git stash pop

# Compare: if "before" now appears faster, thermal effects are a factor
```

## Baseline Storage

Criterion stores baselines in `target/criterion/<benchmark-name>/<baseline-name>/`.

To list existing baselines:

```bash
ls target/criterion/opendeviationbar_processing/process_trades/1000/
# => base/  before/  new/
```

To remove old baselines:

```bash
rm -rf target/criterion/*/before
```

## Filtering Benchmark Groups

Run only specific groups to save time:

```bash
# Only the bar_close_take group
cargo bench --bench opendeviationbar_bench -- "bar_close_take" --baseline before

# Only the 1M tick processing benchmark
cargo bench --bench opendeviationbar_bench -- "process_trades/1000000" --baseline before

# Everything except threshold_calculation
cargo bench --bench opendeviationbar_bench -- --skip "threshold_calculation" --baseline before
```
