feat: added new GH workflow to measure performance (#22)

Author: ch4r10t33r

.github/workflows/README.md

@@ -1,93 +1,148 @@
-# GitHub Actions Workflows
+# GitHub Workflows
 
-## CI Workflow
+This directory contains GitHub Actions workflows for the hash-zig project.
 
-The `ci.yml` workflow runs on every push or pull request to `main`, `master`, or `develop` branches.
+## Workflows
 
-### Jobs
+### 1. CI (`ci.yml`)
+Runs on every push and pull request to main branches:
+- **Lint**: Checks code style and formatting
+- **Test**: Runs unit tests on Ubuntu, macOS, and Windows
+- **Build Examples**: Ensures all examples compile correctly
 
-#### 1. Lint
-- **Runs on:** Ubuntu Latest
-- **Zig Version:** 0.14.1
-- **Steps:**
-  - Checkout code
-  - Setup Zig
-  - Run `zig build lint` (using zlinter)
+### 2. Performance Benchmark (`performance-benchmark.yml`)
+Runs on pull requests and can be triggered manually:
+- **Benchmarks current PR** against the base version
+- **Measures key generation, signing, and verification performance**
+- **Reports performance improvements** in PR comments
+- **Tests multiple lifetimes** (2^10 and 2^16 signatures)
 
-#### 2. Test
-- **Runs on:** Ubuntu, macOS, Windows
-- **Zig Version:** 0.14.1
-- **Matrix Strategy:** Tests on 3 platforms
-- **Steps:**
-  - Checkout code
-  - Setup Zig
-  - Run `zig build test`
-  - Build library with `zig build`
+## Performance Benchmarking
 
-#### 3. Build Examples
-- **Runs on:** Ubuntu Latest
-- **Zig Version:** 0.14.1
-- **Dependencies:** Runs after lint and test jobs succeed
-- **Steps:**
-  - Build library
-  - Run example application
+### What it measures
+- **Key Generation Time**: Time to generate keypairs for different lifetimes
+- **Sign Time**: Time to sign a message
+- **Verify Time**: Time to verify a signature
+- **Memory Usage**: Implicitly through execution time
 
-### Trigger Events
+### How it works
+1. **Checkout current PR** and run benchmarks
+2. **Checkout base version** (previous commit) and run same benchmarks
+3. **Compare results** and calculate percentage improvements
+4. **Report results** in GitHub PR summary and console output
 
-The workflow triggers on:
-- **Push** to main, master, or develop branches
-- **Pull requests** targeting main, master, or develop branches
+### Benchmark Results Format
+The benchmark outputs results in a structured format:
+```
+BENCHMARK_RESULT: 2^10:keygen:1.234567
+BENCHMARK_RESULT: 2^10:sign:0.000123
+BENCHMARK_RESULT: 2^10:verify:0.000456
+```
 
-### Badge
+### Running Benchmarks Locally
 
-The CI status badge in README.md:
+#### Quick Benchmark
+```bash
+zig build benchmark
+```
 
-```markdown
-[![CI](https://github.com/ch4r10t33r/hash-zig/actions/workflows/ci.yml/badge.svg)](https://github.com/ch4r10t33r/hash-zig/actions/workflows/ci.yml)
+#### Detailed Benchmark with Optimizations
+```bash
+zig build benchmark -Doptimize=ReleaseFast
 ```
 
-### Local Testing
+#### Custom Benchmark Script
+```bash
+zig build-exe scripts/benchmark.zig -OReleaseFast --dep hash-zig -Mhash-zig=src/root.zig
+./benchmark
+```
 
-Before pushing, you can run the same checks locally with Zig 0.14.1:
+### Understanding Results
 
-```bash
-# Run linting
-zig build lint
+#### Key Generation
+- **2^10 (1,024 signatures)**: Should complete in ~30-60 seconds
+- **2^16 (65,536 signatures)**: Should complete in ~5-15 minutes
+- **Improvement**: Positive percentage means faster generation
 
-# Run tests
-zig build test
+#### Sign/Verify
+- **Sign**: Should complete in ~100-500ms
+- **Verify**: Should complete in ~50-200ms
+- **Improvement**: Positive percentage means faster operations
 
-# Build library
-zig build
+### Performance Targets
 
-# Run example
-zig build example
-```
+Based on the optimization work, we expect:
+- **2-3x improvement** in key generation time
+- **10-30% improvement** in sign/verify operations
+- **Reduced memory allocations** (measured indirectly through speed)
+
+### Troubleshooting
+
+#### Benchmark Fails
+1. Check that the code compiles: `zig build -Doptimize=ReleaseFast`
+2. Verify tests pass: `zig build test`
+3. Check for memory issues on large lifetimes
+
+#### Inconsistent Results
+1. Run multiple times to get average
+2. Ensure system is not under heavy load
+3. Use ReleaseFast optimization mode
+
+#### CI Workflow Issues
+1. Check that the base commit exists
+2. Verify Zig version compatibility
+3. Check artifact upload permissions
+
+### Adding New Benchmarks
+
+To add new performance tests:
+
+1. **Add to benchmark script** (`scripts/benchmark.zig`):
+   ```zig
+   // New benchmark
+   const new_start = std.time.nanoTimestamp();
+   // ... perform operation ...
+   const new_end = std.time.nanoTimestamp();
+   const new_duration = @as(f64, @floatFromInt(new_end - new_start)) / 1_000_000_000.0;
+   std.debug.print("BENCHMARK_RESULT: new_metric:{d:.6}\n", .{new_duration});
+   ```
 
-### Supported Zig Version
+2. **Update workflow** to capture new metrics:
+   ```yaml
+   NEW_METRIC=$(grep "BENCHMARK_RESULT: new_metric:" results.txt | cut -d: -f2)
+   echo "new_metric=$NEW_METRIC" >> $GITHUB_OUTPUT
+   ```
 
-- **0.14.1** - Required version (zlinter only supports 0.14.x)
+3. **Add to performance analysis**:
+   ```yaml
+   echo "| New Metric | ${{ steps.base.outputs.new_metric }}s | ${{ steps.current.outputs.new_metric }}s | ${improvement}% |" >> $GITHUB_STEP_SUMMARY
+   ```
 
-**Note:** The project uses zlinter which currently only supports Zig 0.14.x. Once zlinter adds support for Zig 0.15+, the CI will be updated.
+## Workflow Triggers
 
-### Platform Support
+### Automatic Triggers
+- **Push to main/master/develop**: Runs CI
+- **Pull Request to main/master/develop**: Runs CI + Performance Benchmark
 
-- **Linux** (Ubuntu Latest)
-- **macOS** (macOS Latest)
-- **Windows** (Windows Latest)
+### Manual Triggers
+- **Workflow Dispatch**: Can manually trigger performance benchmark
+- **API Triggers**: Can be triggered via GitHub API
 
-All tests must pass on all platforms before merging to protected branches.
+## Dependencies
 
-### Linter (zlinter)
+### Required Tools
+- **Zig 0.14.1**: For compilation and testing
+- **bc**: For percentage calculations (available in Ubuntu runners)
+- **git**: For checking out different versions
 
-The project uses [zlinter](https://github.com/kurtwagner/zlinter) - an extendable Zig linter integrated into the build system.
+### Optional Tools
+- **perf**: For detailed performance analysis (if needed)
+- **valgrind**: For memory profiling (if needed)
 
-**Enabled rules:**
-- `field_naming` - Enforce field naming conventions
-- `declaration_naming` - Enforce declaration naming conventions (snake_case)
-- `function_naming` - Enforce function naming conventions
-- `no_unused` - Detect unused declarations
-- `no_deprecated` - Warn about deprecated API usage
+## Best Practices
 
-**Customization:**
-See `build.zig` to add/remove rules or adjust severity levels.
+1. **Always use ReleaseFast** for performance benchmarks
+2. **Run multiple iterations** for stable results
+3. **Document performance targets** in PR descriptions
+4. **Include performance context** in commit messages
+5. **Monitor trends** over time to catch regressions