From 5a7ac77dd156ea478d33798fb5ea954593c5481f Mon Sep 17 00:00:00 2001 From: Richard Hightower Date: Sat, 24 Jan 2026 22:54:22 -0600 Subject: [PATCH 1/2] feat(ci): implement two-tier CI with develop/main branching strategy (#67) Add CI/CD tiered approach to balance development velocity with release quality: Branching Model: - main: Production-ready, protected, requires Full Validation - develop: Integration branch (default), requires Fast CI - feature/*, fix/*: Working branches CI Tiers: - Fast CI (~2-3 min): fmt, clippy, unit tests, Linux IQ smoke test Triggers on: PRs to develop, pushes to feature branches - Full Validation (~10-15 min): IQ (4 platforms) + OQ + PQ + evidence Triggers on: PRs to main, release tags, manual dispatch Workflow Changes: - ci.yml: Converted to Fast CI, triggers on develop/feature branches - validation.yml: Full validation, only PRs to main and releases - iq-validation.yml: Manual-only for formal validation runs Documentation: - constitution.md: Added CI/CD Policy section - docs/devops/BRANCHING.md: Detailed branching workflows - docs/devops/CI_TIERS.md: CI tier explanation - docs/devops/RELEASE_PROCESS.md: Release and hotfix workflows - AGENTS.md: Updated with new workflow instructions Benefits: - Daily development: ~2-3 min feedback loop - Releases: Thorough ~10-15 min validation - Hotfixes: Direct to main with backport to develop --- .github/workflows/ci.yml | 89 +++------- .github/workflows/iq-validation.yml | 16 +- .github/workflows/validation.yml | 18 +- .speckit/constitution.md | 119 ++++++++++++-- AGENTS.md | 79 ++++++--- docs/devops/BRANCHING.md | 175 ++++++++++++++++++++ docs/devops/CI_TIERS.md | 193 ++++++++++++++++++++++ docs/devops/RELEASE_PROCESS.md | 245 ++++++++++++++++++++++++++++ 8 files changed, 828 insertions(+), 106 deletions(-) create mode 100644 docs/devops/BRANCHING.md create mode 100644 docs/devops/CI_TIERS.md create mode 100644 docs/devops/RELEASE_PROCESS.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5d829aa..2d13546 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,27 +1,30 @@ -# CI Pipeline for CCH (Claude Code Hooks) +# Fast CI Pipeline for CCH (Claude Code Hooks) # -# This workflow runs on every push and PR to ensure code quality: +# This workflow provides rapid feedback during daily development: # - Formatting check (rustfmt) # - Linting (clippy) # - Unit tests -# - Integration tests (IQ/OQ/PQ) -# - Code coverage (cargo-llvm-cov) -# - Upload test evidence as artifacts +# - Linux IQ smoke test +# - Code coverage (informational) +# +# Target time: ~2-3 minutes +# +# For full IQ/OQ/PQ validation, see validation.yml (runs on PRs to main) -name: CI +name: Fast CI on: push: - branches: [main, "feature/**", "001-*"] + branches: [develop, "feature/**", "fix/**", "docs/**"] pull_request: - branches: [main] + branches: [develop] env: CARGO_TERM_COLOR: always RUST_BACKTRACE: 1 jobs: - # Format check + # Format check (~30s) fmt: name: Format runs-on: ubuntu-latest @@ -33,7 +36,7 @@ jobs: - name: Check formatting run: cargo fmt --all --check - # Linting with clippy + # Linting with clippy (~1 min) clippy: name: Clippy runs-on: ubuntu-latest @@ -46,7 +49,7 @@ jobs: - name: Run clippy run: cargo clippy --all-targets --all-features -- -D warnings - # Unit tests + # Unit tests (~1 min) test-unit: name: Unit Tests runs-on: ubuntu-latest @@ -57,32 +60,18 @@ jobs: - name: Run unit tests run: cargo test --lib - # Integration tests (IQ/OQ/PQ) - test-integration: - name: Integration Tests (${{ matrix.test }}) + # Linux IQ smoke test (~1 min) + test-iq-smoke: + name: IQ Smoke Test (Linux) runs-on: ubuntu-latest - strategy: - matrix: - test: [iq_installation, oq_us1_blocking, oq_us2_injection, oq_us3_validators, oq_us4_permissions, oq_us5_logging, pq_performance] steps: - uses: actions/checkout@v4 - uses: dtolnay/rust-toolchain@stable - uses: Swatinem/rust-cache@v2 - - name: Set up Python (for validators) - uses: actions/setup-python@v5 - with: - python-version: '3.11' - - name: Run integration test - run: cargo test --test ${{ matrix.test }} - - name: Upload test evidence - if: always() - uses: actions/upload-artifact@v4 - with: - name: test-evidence-${{ matrix.test }} - path: cch_cli/target/test-evidence/ - if-no-files-found: ignore + - name: Run IQ tests + run: cargo test iq_ -- --nocapture - # Code coverage + # Code coverage (informational, ~2 min) coverage: name: Code Coverage runs-on: ubuntu-latest @@ -113,38 +102,11 @@ jobs: name: coverage-report path: lcov.info - # Build release binary - build: - name: Build Release - runs-on: ${{ matrix.os }} - strategy: - matrix: - include: - - os: ubuntu-latest - target: x86_64-unknown-linux-gnu - - os: macos-latest - target: x86_64-apple-darwin - - os: macos-latest - target: aarch64-apple-darwin - steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - with: - targets: ${{ matrix.target }} - - uses: Swatinem/rust-cache@v2 - - name: Build release - run: cargo build --release --target ${{ matrix.target }} - - name: Upload binary - uses: actions/upload-artifact@v4 - with: - name: cch-${{ matrix.target }} - path: target/${{ matrix.target }}/release/cch - # Summary job that requires all others to pass ci-success: - name: CI Success + name: Fast CI Success runs-on: ubuntu-latest - needs: [fmt, clippy, test-unit, test-integration, coverage, build] + needs: [fmt, clippy, test-unit, test-iq-smoke] if: always() steps: - name: Check all jobs passed @@ -152,9 +114,8 @@ jobs: if [[ "${{ needs.fmt.result }}" != "success" ]] || \ [[ "${{ needs.clippy.result }}" != "success" ]] || \ [[ "${{ needs.test-unit.result }}" != "success" ]] || \ - [[ "${{ needs.test-integration.result }}" != "success" ]] || \ - [[ "${{ needs.build.result }}" != "success" ]]; then - echo "One or more jobs failed" + [[ "${{ needs.test-iq-smoke.result }}" != "success" ]]; then + echo "One or more Fast CI jobs failed" exit 1 fi - echo "All CI jobs passed successfully" + echo "All Fast CI jobs passed successfully" diff --git a/.github/workflows/iq-validation.yml b/.github/workflows/iq-validation.yml index 20fcc7b..1506641 100644 --- a/.github/workflows/iq-validation.yml +++ b/.github/workflows/iq-validation.yml @@ -3,6 +3,13 @@ # Validates CCH installation and basic functionality across all supported platforms. # This is the first phase of IQ/OQ/PQ validation framework. # +# NOTE: This workflow is MANUAL-ONLY. It does not run automatically. +# Use this for formal validation runs and compliance audits. +# +# For automatic validation, use: +# - Fast CI (ci.yml) - runs on PRs to develop +# - Full Validation (validation.yml) - runs on PRs to main +# # Platforms tested: # - macOS ARM64 (M1/M2/M3) # - macOS Intel (x86_64) @@ -11,19 +18,16 @@ # # Reference: docs/IQ_OQ_PQ_IntegrationTesting.md -name: IQ Validation +name: IQ Validation (Manual) on: - push: - branches: [main] - pull_request: - branches: [main] + # Manual trigger only - for formal validation runs workflow_dispatch: inputs: evidence_collection: description: 'Collect formal evidence for validation report' type: boolean - default: false + default: true env: CARGO_TERM_COLOR: always diff --git a/.github/workflows/validation.yml b/.github/workflows/validation.yml index 69e2355..fd4d9d2 100644 --- a/.github/workflows/validation.yml +++ b/.github/workflows/validation.yml @@ -1,22 +1,28 @@ -# Combined IQ/OQ/PQ Validation Workflow +# Full IQ/OQ/PQ Validation Workflow # # Orchestrates the full validation sequence: # 1. IQ (Installation Qualification) - Cross-platform installation verification # 2. OQ (Operational Qualification) - Functional testing of all features # 3. PQ (Performance Qualification) - Performance benchmarks and limits # -# This workflow serves as the release gate - all phases must pass. +# This workflow serves as the RELEASE GATE - all phases must pass. +# Only runs on PRs to main, release tags, or manual dispatch. +# +# For daily development, use Fast CI (ci.yml) which runs on develop. # # Reference: docs/IQ_OQ_PQ_IntegrationTesting.md +# Reference: docs/devops/CI_TIERS.md -name: IQ/OQ/PQ Validation +name: Full Validation on: - push: - branches: [main] - tags: ['v*'] + # Only PRs targeting main trigger full validation pull_request: branches: [main] + # Release tags trigger full validation + push: + tags: ['v*'] + # Manual trigger for formal validation runs workflow_dispatch: inputs: skip_iq: diff --git a/.speckit/constitution.md b/.speckit/constitution.md index 8cca282..f010f99 100644 --- a/.speckit/constitution.md +++ b/.speckit/constitution.md @@ -26,10 +26,31 @@ This positions CCH as comparable to: ## Git Workflow Principles +### Branching Model + +``` +main (protected) <- Production-ready, fully validated + ^ + | +develop (default) <- Integration branch, fast CI + ^ + | +feature/* | fix/* <- Short-lived working branches +``` + +| Branch | Purpose | CI Level | Protection | +|--------|---------|----------|------------| +| `main` | Production-ready releases | Full Validation | Protected, requires IQ/OQ/PQ | +| `develop` | Integration branch (default) | Fast CI | Protected, requires Fast CI | +| `feature/*` | Active development | Fast CI | None | +| `fix/*` | Bug fixes | Fast CI | None | +| `release/*` | Release candidates | Full Validation | None | +| `hotfix/*` | Emergency fixes to main | Full Validation | None | + ### Feature Branch Requirement -- **NEVER commit directly to `main`** - This is a non-negotiable principle +- **NEVER commit directly to `main` or `develop`** - This is a non-negotiable principle - All feature work MUST be done in a dedicated feature branch -- Pull Requests are REQUIRED for all changes to `main` +- Pull Requests are REQUIRED for all changes - Code review via PR ensures quality and knowledge sharing ### Branch Naming Convention @@ -37,15 +58,31 @@ This positions CCH as comparable to: - Bugfixes: `fix/` (e.g., `fix/config-parsing-error`) - Documentation: `docs/` (e.g., `docs/update-readme`) - Releases: `release/` (e.g., `release/v1.0.0`) +- Hotfixes: `hotfix/` (e.g., `hotfix/critical-security-fix`) -### PR Workflow -1. Create feature branch from `main` +### Standard PR Workflow (Daily Development) +1. Create feature branch from `develop` 2. Implement changes with atomic, conventional commits -3. **Run all pre-commit checks locally** (see below) -4. Push branch and create Pull Request -5. Request review and address feedback -6. Merge via GitHub (squash or merge commit as appropriate) -7. Delete feature branch after merge +3. **Run pre-commit checks locally** (see below) +4. Push branch and create Pull Request **targeting `develop`** +5. Fast CI runs (~2-3 minutes) +6. Request review and address feedback +7. Merge to `develop` via GitHub +8. Delete feature branch after merge + +### Release Workflow (Production Deployment) +1. Create PR from `develop` to `main` +2. Full IQ/OQ/PQ validation runs (~10-15 minutes) +3. All 4 platforms tested (macOS ARM64, Intel, Linux, Windows) +4. Evidence artifacts collected +5. Merge to `main` only after all validation passes +6. Tag release from `main` + +### Hotfix Workflow (Emergency Fixes) +1. Create `hotfix/*` branch from `main` +2. Implement fix with minimal changes +3. Create PR to `main` (triggers full validation) +4. After merge to `main`, backport to `develop` ### Pre-Commit Checks (MANDATORY) @@ -73,7 +110,69 @@ cd cch_cli && cargo fmt && cargo clippy --all-targets --all-features -- -D warni ``` ### Rationale -Direct commits to `main` bypass code review, risk introducing bugs, and make it difficult to revert changes. Feature branches enable parallel development, clean history, and proper CI/CD validation before merge. +- **Two-branch model** enables fast iteration on `develop` while maintaining production stability on `main` +- **Fast CI on develop** provides rapid feedback (~2-3 min) during active development +- **Full validation on main** ensures releases are thoroughly tested across all platforms +- Direct commits bypass code review, risk introducing bugs, and make it difficult to revert changes + +--- + +## CI/CD Policy + +### CI Tiers + +| Tier | Trigger | Duration | What Runs | +|------|---------|----------|-----------| +| **Fast CI** | Push to `develop`, `feature/*`; PRs to `develop` | ~2-3 min | fmt, clippy, unit tests, Linux IQ smoke test | +| **Full Validation** | PRs to `main`, release tags, manual dispatch | ~10-15 min | Fast CI + IQ (4 platforms) + OQ + PQ + evidence | + +### Fast CI (~2-3 minutes) +**Purpose:** Rapid feedback during active development + +**Jobs:** +- Format check (`cargo fmt --check`) +- Linting (`cargo clippy`) +- Unit tests (`cargo test --lib`) +- Linux IQ smoke test (`cargo test iq_`) +- Code coverage (report only, non-blocking) + +**When it runs:** +- Every push to `develop` or `feature/*` branches +- Every PR targeting `develop` + +### Full Validation (~10-15 minutes) +**Purpose:** Release gate validation ensuring production readiness + +**Jobs:** +- All Fast CI jobs +- IQ on 4 platforms (macOS ARM64, macOS Intel, Linux, Windows) +- Full OQ test suite (US1-US5) +- PQ benchmarks (performance, memory) +- Evidence collection and artifact upload + +**When it runs:** +- PRs targeting `main` +- Release tags (`v*`) +- Manual workflow dispatch + +### Validation Gates + +| Event | Required Checks | Blocking | +|-------|-----------------|----------| +| PR to `develop` | Fast CI passes | Yes | +| PR to `main` | Full IQ/OQ/PQ Validation passes | Yes | +| Release tag | Full Validation already passed on `main` | Yes | + +### Evidence Collection +Full validation automatically collects and uploads: +- IQ evidence per platform +- OQ test results +- PQ benchmark data +- Combined validation report + +Evidence is stored as GitHub Actions artifacts and can be downloaded for compliance audits. + +Reference: [CI Tiers Documentation](docs/devops/CI_TIERS.md) --- diff --git a/AGENTS.md b/AGENTS.md index 56010a3..768b843 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,39 +6,78 @@ **CRITICAL: Always use feature branches for all work.** -- **NEVER commit directly to `main`** - All feature work MUST be done in a feature branch -- Create a feature branch before starting any work: `git checkout -b feature/` -- Push the feature branch and create a Pull Request for review -- Only merge to `main` via PR after review +### Branching Model -**Branch Naming Convention:** +``` +main (protected) <- Production-ready, fully validated + ^ + | +develop (default) <- Integration branch, fast CI (~2-3 min) + ^ + | +feature/* | fix/* <- Short-lived working branches +``` + +### Branch Rules +- **NEVER commit directly to `main` or `develop`** +- Create feature branches from `develop`: `git checkout develop && git checkout -b feature/` +- PRs to `develop` run Fast CI (~2-3 min) +- PRs to `main` run Full Validation (~10-15 min) - use for releases only + +### Branch Naming Convention - Features: `feature/` (e.g., `feature/add-debug-command`) - Bugfixes: `fix/` (e.g., `fix/config-parsing-error`) - Documentation: `docs/` (e.g., `docs/update-readme`) +- Hotfixes: `hotfix/` (for emergency fixes to main) + +### Daily Development Workflow +```bash +# 1. Start from develop +git checkout develop && git pull origin develop + +# 2. Create feature branch +git checkout -b feature/ + +# 3. Make changes, run pre-commit checks +cd cch_cli && cargo fmt && cargo clippy --all-targets --all-features -- -D warnings && cargo test + +# 4. Push and create PR targeting develop +git push -u origin feature/ +gh pr create --base develop + +# 5. After merge, clean up +git checkout develop && git pull && git branch -d feature/ +``` -**Workflow:** -1. `git checkout -b feature/` - Create feature branch -2. Make changes and commit with conventional commit messages -3. **Run all checks before committing** (see Pre-Commit Checks below) -4. `git push -u origin feature/` - Push to remote -5. Create PR via `gh pr create` or GitHub UI -6. Merge after review +### Release Workflow (to main) +```bash +# Create PR from develop to main +gh pr create --base main --head develop --title "Release: v1.x.x" +# Wait for Full Validation (~10-15 min) +# Merge after all IQ/OQ/PQ tests pass +``` -**Pre-Commit Checks (MANDATORY):** -Before every commit, run these checks locally to avoid CI failures: +### Hotfix Workflow ```bash -cd cch_cli -cargo fmt --check # Check formatting -cargo clippy --all-targets --all-features -- -D warnings # Linting -cargo test # All tests must pass +# Create hotfix from main +git checkout main && git checkout -b hotfix/ +# Fix, PR to main, then backport to develop ``` -Or run all checks with: +### Pre-Commit Checks (MANDATORY) ```bash cd cch_cli && cargo fmt && cargo clippy --all-targets --all-features -- -D warnings && cargo test ``` -**NEVER commit if any of these checks fail.** Fix all issues first. +**NEVER commit if any check fails.** Fix all issues first. + +### CI Tiers +| Target | CI Level | Time | What Runs | +|--------|----------|------|-----------| +| PR to `develop` | Fast CI | ~2-3 min | fmt, clippy, unit tests, Linux IQ | +| PR to `main` | Full Validation | ~10-15 min | Fast CI + IQ (4 platforms) + OQ + PQ | + +Reference: [docs/devops/BRANCHING.md](docs/devops/BRANCHING.md) | [docs/devops/CI_TIERS.md](docs/devops/CI_TIERS.md) diff --git a/docs/devops/BRANCHING.md b/docs/devops/BRANCHING.md new file mode 100644 index 0000000..6c694d8 --- /dev/null +++ b/docs/devops/BRANCHING.md @@ -0,0 +1,175 @@ +# Branching Strategy + +## Overview + +CCH uses a two-branch model optimized for rapid development with production stability: + +``` +main (protected) <- Production-ready, fully validated + ^ + | +develop (default) <- Integration branch, fast CI + ^ + | +feature/* | fix/* <- Short-lived working branches +``` + +## Branch Descriptions + +### `main` - Production Branch +- **Purpose:** Production-ready code only +- **Protection:** Full IQ/OQ/PQ validation required +- **Who merges:** Via PR from `develop` after full validation +- **Direct commits:** NEVER allowed + +### `develop` - Integration Branch +- **Purpose:** Integration of completed features +- **Protection:** Fast CI required +- **Default branch:** Yes (clone targets this) +- **Who merges:** Via PR from feature branches +- **Direct commits:** NEVER allowed + +### `feature/*` - Feature Branches +- **Purpose:** Active development work +- **Naming:** `feature/` +- **Created from:** `develop` +- **Merged to:** `develop` +- **Lifetime:** Short-lived (days, not weeks) + +### `fix/*` - Bug Fix Branches +- **Purpose:** Bug fixes for develop +- **Naming:** `fix/` +- **Created from:** `develop` +- **Merged to:** `develop` + +### `hotfix/*` - Emergency Fixes +- **Purpose:** Critical fixes that must go directly to production +- **Naming:** `hotfix/` +- **Created from:** `main` +- **Merged to:** `main`, then backported to `develop` +- **Requires:** Full validation before merge + +### `release/*` - Release Candidates +- **Purpose:** Preparing a release +- **Naming:** `release/v` +- **Created from:** `develop` +- **Merged to:** `main` and `develop` + +--- + +## Workflows + +### Daily Development Workflow + +```bash +# 1. Start from develop +git checkout develop +git pull origin develop + +# 2. Create feature branch +git checkout -b feature/my-new-feature + +# 3. Make changes, commit frequently +git add . +git commit -m "feat: add new capability" + +# 4. Run pre-commit checks +cd cch_cli && cargo fmt && cargo clippy --all-targets --all-features -- -D warnings && cargo test + +# 5. Push and create PR +git push -u origin feature/my-new-feature +gh pr create --base develop --title "feat: add new capability" + +# 6. After PR approval and merge, clean up +git checkout develop +git pull origin develop +git branch -d feature/my-new-feature +``` + +### Release Workflow + +```bash +# 1. Ensure develop is stable +git checkout develop +git pull origin develop + +# 2. Create PR to main +gh pr create --base main --head develop --title "Release: merge develop to main" + +# 3. Wait for full validation (~10-15 min) +# - IQ runs on 4 platforms +# - OQ runs all test suites +# - PQ runs benchmarks +# - Evidence is collected + +# 4. After validation passes, merge PR + +# 5. Tag the release +git checkout main +git pull origin main +git tag -a v1.x.x -m "Release v1.x.x" +git push origin v1.x.x +``` + +### Hotfix Workflow + +```bash +# 1. Create hotfix from main +git checkout main +git pull origin main +git checkout -b hotfix/critical-issue + +# 2. Implement minimal fix +git add . +git commit -m "fix: critical security issue" + +# 3. Create PR to main (triggers full validation) +git push -u origin hotfix/critical-issue +gh pr create --base main --title "hotfix: critical security issue" + +# 4. After merge to main, backport to develop +git checkout develop +git pull origin develop +git cherry-pick +git push origin develop +``` + +--- + +## CI Integration + +| Branch Target | CI Workflow | Duration | Blocking | +|---------------|-------------|----------|----------| +| PR to `develop` | Fast CI | ~2-3 min | Yes | +| PR to `main` | Full Validation | ~10-15 min | Yes | +| Push to `feature/*` | Fast CI | ~2-3 min | No | + +See [CI_TIERS.md](CI_TIERS.md) for detailed CI configuration. + +--- + +## Best Practices + +### Do +- Keep feature branches short-lived (< 1 week) +- Rebase feature branches on develop before PR +- Write descriptive PR titles following conventional commits +- Delete branches after merge + +### Don't +- Commit directly to `main` or `develop` +- Let feature branches diverge significantly +- Merge without CI passing +- Force push to shared branches + +--- + +## Quick Reference + +| Task | Command | +|------|---------| +| Start new feature | `git checkout develop && git pull && git checkout -b feature/name` | +| Create PR to develop | `gh pr create --base develop` | +| Create PR to main | `gh pr create --base main --head develop` | +| Delete local branch | `git branch -d feature/name` | +| Delete remote branch | `git push origin --delete feature/name` | diff --git a/docs/devops/CI_TIERS.md b/docs/devops/CI_TIERS.md new file mode 100644 index 0000000..96e247d --- /dev/null +++ b/docs/devops/CI_TIERS.md @@ -0,0 +1,193 @@ +# CI Tiers + +## Overview + +CCH uses a two-tier CI system to balance development velocity with release quality: + +| Tier | When | Duration | Purpose | +|------|------|----------|---------| +| **Fast CI** | PRs to `develop`, feature pushes | ~2-3 min | Rapid feedback | +| **Full Validation** | PRs to `main`, releases | ~10-15 min | Release gate | + +--- + +## Fast CI + +**Workflow:** `.github/workflows/ci.yml` + +### Triggers +- Push to `develop` branch +- Push to `feature/*` branches +- Pull requests targeting `develop` + +### Jobs + +| Job | Description | Duration | +|-----|-------------|----------| +| `fmt` | Check code formatting | ~30s | +| `clippy` | Lint with clippy | ~1 min | +| `test-unit` | Run unit tests | ~1 min | +| `test-iq-smoke` | Linux IQ smoke test | ~1 min | +| `coverage` | Generate coverage report | ~2 min | + +### What It Validates +- Code compiles without errors +- Code follows formatting standards +- No clippy warnings +- Unit tests pass +- Basic IQ installation works on Linux + +### What It Skips +- Multi-platform builds +- Full OQ test suite +- PQ performance tests +- Evidence collection + +### When to Use +- Daily development +- Quick iterations +- Feature development +- Bug fixes + +--- + +## Full Validation + +**Workflow:** `.github/workflows/validation.yml` + +### Triggers +- Pull requests targeting `main` +- Release tags (`v*`) +- Manual dispatch (`workflow_dispatch`) + +### Jobs + +| Phase | Jobs | Duration | +|-------|------|----------| +| IQ | 4 platform builds (macOS ARM64, Intel, Linux, Windows) | ~5 min | +| OQ | US1-US5 test suites | ~3 min | +| PQ | Performance and memory tests | ~3 min | +| Report | Generate validation report | ~1 min | + +### What It Validates +- Installation works on all 4 platforms +- All operational features work correctly +- Performance meets requirements +- Memory usage is acceptable +- No regressions from previous release + +### Evidence Collected +- IQ evidence per platform +- OQ test results (JSON) +- PQ benchmark data +- Combined validation report + +### When to Use +- Merging to production (`main`) +- Creating releases +- Formal validation audits + +--- + +## Workflow Files + +### Fast CI (`.github/workflows/ci.yml`) +```yaml +on: + push: + branches: [develop, "feature/**"] + pull_request: + branches: [develop] +``` + +### Full Validation (`.github/workflows/validation.yml`) +```yaml +on: + pull_request: + branches: [main] + push: + tags: ['v*'] + workflow_dispatch: +``` + +### IQ Validation (`.github/workflows/iq-validation.yml`) +```yaml +on: + workflow_dispatch: # Manual only +``` + +--- + +## Running Locally + +### Fast CI Equivalent +```bash +cd cch_cli +cargo fmt --check +cargo clippy --all-targets --all-features -- -D warnings +cargo test --lib +cargo test iq_ +``` + +### Full Validation Equivalent +```bash +# Fast CI checks +cd cch_cli +cargo fmt --check +cargo clippy --all-targets --all-features -- -D warnings +cargo test + +# Evidence collection +cd .. +./scripts/collect-iq-evidence.sh --release +./scripts/collect-oq-evidence.sh --release +./scripts/collect-pq-evidence.sh --release +./scripts/generate-validation-report.sh +``` + +--- + +## Interpreting Failures + +### Fast CI Failures + +| Job | Failure Meaning | Fix | +|-----|-----------------|-----| +| `fmt` | Code not formatted | Run `cargo fmt` | +| `clippy` | Lint warnings | Fix warnings or add `#[allow(...)]` | +| `test-unit` | Unit test failed | Fix test or code | +| `test-iq-smoke` | Installation broken | Check build/install logic | + +### Full Validation Failures + +| Phase | Failure Meaning | Action | +|-------|-----------------|--------| +| IQ platform failure | Build/install broken on that platform | Check platform-specific code | +| OQ failure | Feature regression | Review test failure details | +| PQ failure | Performance regression | Profile and optimize | + +--- + +## Coverage + +Coverage runs in **both** tiers: +- **Fast CI:** Generates report, non-blocking warning if < 80% +- **Full Validation:** Same behavior, artifacts uploaded + +Coverage is informational - it doesn't block PRs, but low coverage generates a warning. + +--- + +## Manual Validation + +For formal validation runs (compliance, audits): + +```bash +# Trigger IQ validation manually +gh workflow run iq-validation.yml + +# Or run full validation +gh workflow run validation.yml +``` + +Evidence artifacts will be available in the GitHub Actions run. diff --git a/docs/devops/RELEASE_PROCESS.md b/docs/devops/RELEASE_PROCESS.md new file mode 100644 index 0000000..b19b2ee --- /dev/null +++ b/docs/devops/RELEASE_PROCESS.md @@ -0,0 +1,245 @@ +# Release Process + +## Overview + +CCH releases follow a structured process ensuring quality and traceability: + +1. **Development** on `develop` branch (Fast CI) +2. **Validation** via PR to `main` (Full IQ/OQ/PQ) +3. **Release** tag from `main` +4. **Deployment** via GitHub Releases + +--- + +## Pre-Release Checklist + +Before creating a release PR: + +- [ ] All planned features merged to `develop` +- [ ] All tests passing on `develop` +- [ ] Version updated in `cch_cli/Cargo.toml` +- [ ] CHANGELOG updated +- [ ] Documentation updated + +--- + +## Release Workflow + +### Step 1: Prepare Release + +```bash +# Ensure develop is clean +git checkout develop +git pull origin develop + +# Verify all tests pass +cd cch_cli && cargo test +cd .. + +# Update version if needed +# Edit cch_cli/Cargo.toml +``` + +### Step 2: Create Release PR + +```bash +# Create PR from develop to main +gh pr create \ + --base main \ + --head develop \ + --title "Release: v1.x.x" \ + --body "## Release v1.x.x + +### Changes +- Feature A +- Feature B +- Bug fix C + +### Validation +Full IQ/OQ/PQ validation will run automatically." +``` + +### Step 3: Wait for Validation + +The PR triggers Full Validation (~10-15 minutes): + +| Phase | What Runs | +|-------|-----------| +| IQ | 4-platform installation tests | +| OQ | All operational test suites | +| PQ | Performance and memory tests | +| Report | Validation summary generated | + +**All phases must pass before merge.** + +### Step 4: Review Evidence + +Download validation artifacts from the GitHub Actions run: + +1. Go to Actions tab +2. Find the validation workflow run +3. Download artifacts: + - `iq-evidence-*` (per platform) + - `oq-evidence` + - `pq-evidence` + - `validation-report` + +### Step 5: Merge and Tag + +```bash +# After PR approval and validation passes +# Merge via GitHub UI + +# Pull the merged main +git checkout main +git pull origin main + +# Create annotated tag +git tag -a v1.x.x -m "Release v1.x.x + +Changes: +- Feature A +- Feature B +- Bug fix C" + +# Push tag +git push origin v1.x.x +``` + +### Step 6: Create GitHub Release + +```bash +gh release create v1.x.x \ + --title "CCH v1.x.x" \ + --notes "## What's New + +### Features +- Feature A +- Feature B + +### Bug Fixes +- Bug fix C + +### Validation +- IQ: Passed on macOS (ARM64, Intel), Linux, Windows +- OQ: All test suites passed +- PQ: Performance requirements met" +``` + +--- + +## Hotfix Release + +For critical fixes that can't wait for normal release cycle: + +### Step 1: Create Hotfix + +```bash +git checkout main +git pull origin main +git checkout -b hotfix/critical-issue +``` + +### Step 2: Implement Fix + +```bash +# Minimal changes only +git add . +git commit -m "fix: critical security issue" +``` + +### Step 3: Create PR to Main + +```bash +git push -u origin hotfix/critical-issue +gh pr create \ + --base main \ + --title "hotfix: critical security issue" \ + --body "## Hotfix + +### Issue +Description of the critical issue. + +### Fix +Description of the fix. + +### Testing +- [ ] Verified fix locally +- [ ] Full validation will run" +``` + +### Step 4: After Merge, Backport + +```bash +# After hotfix merged to main +git checkout develop +git pull origin develop +git cherry-pick +git push origin develop +``` + +--- + +## Version Numbering + +CCH follows [Semantic Versioning](https://semver.org/): + +| Version | When to Increment | +|---------|-------------------| +| MAJOR (1.x.x) | Breaking changes | +| MINOR (x.1.x) | New features, backward compatible | +| PATCH (x.x.1) | Bug fixes, backward compatible | + +--- + +## Evidence Retention + +Validation evidence is retained per release: + +| Release Type | Retention | +|--------------|-----------| +| Major | Indefinite | +| Minor | 2 years minimum | +| Patch | 1 year minimum | + +Store evidence in `docs/validation/sign-off/v{version}/`. + +--- + +## Rollback Procedure + +If a release has critical issues: + +```bash +# Identify last good release +git log --oneline --tags + +# Create hotfix from last good release +git checkout v1.x.x # last good version +git checkout -b hotfix/rollback-issue + +# Cherry-pick fix or revert problematic commit +git revert + +# Follow hotfix process above +``` + +--- + +## Automation + +### Taskfile Commands + +```bash +# Collect all validation evidence +task collect-all + +# Generate validation report +task validation-report +``` + +### GitHub Actions + +- **Release tag push** triggers release workflow +- **Binaries** automatically built and attached to release +- **Evidence** available as workflow artifacts From b3ab00750dae4844c1b0e9eade15fa764ee804fb Mon Sep 17 00:00:00 2001 From: Richard Hightower Date: Sat, 24 Jan 2026 23:00:15 -0600 Subject: [PATCH 2/2] fix(ci): update macOS Intel runner from macos-13 to macos-15-intel (#69) macOS 13 runners were retired by GitHub in Jan 2026. Using macos-15-intel as the new x86_64 runner (supported until Aug 2027). Reference: actions/runner-images#13046 --- .github/workflows/validation.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/validation.yml b/.github/workflows/validation.yml index fd4d9d2..e385bd0 100644 --- a/.github/workflows/validation.yml +++ b/.github/workflows/validation.yml @@ -68,7 +68,9 @@ jobs: iq-macos-intel: name: IQ - macOS Intel if: ${{ github.event.inputs.skip_iq != 'true' }} - runs-on: macos-13 + # Note: macos-13 was retired Jan 2026 (see actions/runner-images#13046) + # Using macos-15-intel - last supported x86_64 image (until Aug 2027) + runs-on: macos-15-intel steps: - uses: actions/checkout@v4 - uses: dtolnay/rust-toolchain@stable