CI/CD Validation & Merge Workflow

This skill provides guidance on validation workflows, CI/CD processes, and merge procedures for cqlite.

When to Use This Skill

• Running pre-push validation
• Preparing pull requests
• Monitoring CI pipeline
• Merging changes
• Preparing releases
• Troubleshooting CI failures

Pre-Push Validation Checklist

See validation-checklist.md for complete steps.

Quick Validation

# Run all pre-push checks
./scripts/ci/validate-cleanup.sh

Manual Step-by-Step

1. Format Code

cargo fmt --all
git add -u
git commit -m "style: cargo fmt" || echo "No formatting needed"

2. Clippy (Zero Warnings)

# MUST pass with -D warnings (warnings = errors)
cargo clippy --package cqlite-core --lib --all-features -- -D warnings

Requirements:

• Zero warnings
• Fix all issues before proceeding
• No #[allow(clippy::...)] without justification

3. Build (Minimal Features)

# M1 scope: reading only, no default features
cargo build --package cqlite-core --no-default-features --features=all-compression

Must succeed - tests feature gate correctness.

4. Build (All Features)

# Full feature set
cargo build --package cqlite-core --all-features

Must succeed - tests complete build.

5. Run Tests (Library)

# Run all library tests
cargo test --package cqlite-core --lib --all-features

Track test count - should not decrease unexpectedly.

6. Run Integration Tests

# Run integration tests
cargo test --test '*'

Must pass - validates end-to-end functionality.

7. Coverage Check

# Generate coverage report
cargo tarpaulin --out Html --output-dir coverage/

Target: ≥90% coverage (PRD requirement)

Feature Flag Testing

M1 Feature Gates

Core reading (minimal):

cargo build --package cqlite-core \
    --no-default-features \
    --features=all-compression

With benchmarks:

cargo build --package cqlite-core \
    --no-default-features \
    --features=all-compression,benchmarks

All features:

cargo build --package cqlite-core --all-features

Validate Feature Combinations

# Test feature matrix
for features in "all-compression" "all-compression,benchmarks" "all-features"; do
    echo "Testing: $features"
    cargo test --package cqlite-core --no-default-features --features=$features
done

CI Pipeline

GitHub Actions Workflow

Located: .github/workflows/rust.yml

Jobs:

1. Format Check

   • Runs cargo fmt -- --check
   • Fast fail if unformatted

2. Clippy

   • Runs with -D warnings
   • Zero warnings required

3. Build Matrix

   • Minimal features
   • All features
   • Multiple Rust versions (stable, nightly)

4. Test Matrix

   • Linux, macOS, Windows
   • Unit + integration tests

5. Coverage

   • Generates with tarpaulin
   • Uploads to Codecov
   • Gates on 90% threshold

Monitoring CI

View Status

# List recent runs
gh run list --branch <branch-name> --limit 5

# View specific run
gh run view <run-id>

# Watch live
gh run watch <run-id>

Check Failures

# Download logs
gh run view <run-id> --log

# Download failed job logs
gh run view <run-id> --log-failed

Merge Process

See merge-process.md for detailed workflow.

Prerequisites

Before merging:

• ✅ All CI checks green (10/10)
• ✅ Code review approved
• ✅ Branch up to date with main
• ✅ No conflicts
• ✅ Coverage ≥90%

Merge Methods

Squash merge (default for cleanup):

gh pr merge <pr-number> --squash --delete-branch

Merge commit (for feature branches):

gh pr merge <pr-number> --merge --delete-branch

Rebase (for clean history):

gh pr merge <pr-number> --rebase --delete-branch

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types:

• feat: New feature
• fix: Bug fix
• refactor: Code refactoring
• perf: Performance improvement
• test: Test additions/changes
• docs: Documentation
• style: Formatting
• chore: Build/tooling
• cleanup: Dead code removal

Example:

feat(parser): add support for duration CQL type

Implement deserialization for duration type consisting of
three VInts (months, days, nanoseconds).

- Add Duration variant to CqlType enum
- Implement parse_duration() with VInt handling
- Add property tests for edge cases

Closes #123

Error Handling

Clippy Failures

Common issues:

# Unused imports
cargo clippy --fix

# Unnecessary clones
# Review each and remove if safe

# Dead code warnings
# Expected for cleanup issues - document

Test Failures

Debugging:

# Run single test with output
cargo test --test test_name -- --nocapture

# Run with backtrace
RUST_BACKTRACE=1 cargo test test_name

# Run with logging
RUST_LOG=debug cargo test test_name

Build Failures

Feature flag issues:

# Check feature dependencies in Cargo.toml
[features]
default = ["all-compression"]
all-compression = ["lz4", "snap", "flate2"]
benchmarks = []  # NOT in default

Dependency issues:

# Clean and rebuild
cargo clean
cargo build

Coverage Failures

Below 90%:

1. Identify uncovered lines
2. Add unit tests for uncovered code
3. Add property tests for edge cases
4. Document why coverage can't reach 90% (if applicable)

Release Process

Pre-Release Checklist

1. All tests pass

   cargo test --all-features

2. Benchmarks run

   cargo bench --features=benchmarks

3. Documentation builds

   cargo doc --no-deps --all-features

4. Examples work

   cargo run --example basic_usage

5. Update CHANGELOG.md

   ## [0.1.0] - 2025-10-21
   ### Added
   - Initial release
   - Cassandra 5.0 SSTable parsing
   - All CQL types supported

6. Update version

   # Cargo.toml
   [package]
   version = "0.1.0"

Creating Release

# Tag version
git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

# Create GitHub release
gh release create v0.1.0 \
    --title "v0.1.0 - Initial Release" \
    --notes-file RELEASE_NOTES.md \
    --draft  # Remove --draft when ready

PRD Alignment

Milestone M1 (Core Reading Library):

• 95% test coverage requirement
• Zero clippy warnings
• All CQL types validated

Milestone M6 (Performance & Release):

• Benchmarks vs native tools
• Release packaging
• 90% codecov gate (stricter than M1)

Common Scenarios

Scenario 1: Pre-Push Validation

# Quick check before push
cargo fmt --all
cargo clippy --package cqlite-core --lib --all-features -- -D warnings
cargo test --package cqlite-core --lib

# If all pass:
git push origin feature/my-branch

Scenario 2: CI Failure Investigation

# Check CI logs
gh run view --log

# Reproduce locally
cargo test --package cqlite-core --lib --features=all-compression

# Fix and push
git commit --amend
git push --force-with-lease origin feature/my-branch

Scenario 3: Merge Blocked by Coverage

# Generate coverage report
cargo tarpaulin --out Html

# Open report
open tarpaulin-report.html

# Identify uncovered code
# Add tests
# Re-run coverage

Automation

Pre-Commit Hook

# .git/hooks/pre-commit
#!/bin/bash
set -e

echo "Running pre-commit checks..."

# Format
cargo fmt --all -- --check

# Clippy
cargo clippy --package cqlite-core --lib --all-features -- -D warnings

# Tests
cargo test --package cqlite-core --lib

echo "Pre-commit checks passed!"

Pre-Push Hook

# .git/hooks/pre-push
#!/bin/bash
set -e

echo "Running pre-push validation..."

# Full validation
./scripts/ci/validate-cleanup.sh

echo "Pre-push validation passed!"

Troubleshooting

Tests Pass Locally, Fail in CI

Possible causes:

• Platform-specific issues (Windows vs Linux)
• Timing issues in async tests
• File path differences

Solution:

# Run in Docker matching CI environment
docker run --rm -v $(pwd):/workspace -w /workspace rust:latest \
    cargo test --all-features

Clippy Different Results Locally vs CI

Cause: Different Rust versions

Solution:

# Check Rust version
rustc --version

# Use same as CI (check .github/workflows/rust.yml)
rustup install 1.70.0
rustup default 1.70.0

Coverage Unstable

Cause: Non-deterministic code or flaky tests

Solution:

• Run coverage multiple times
• Identify unstable lines
• Fix flaky tests

Best Practices

1. Validate locally before pushing

   • Saves CI resources
   • Faster feedback loop

2. Fix clippy warnings immediately

   • Don't accumulate tech debt
   • Easier to fix in context

3. Keep PRs small

   • Easier to review
   • Easier to revert if needed

4. Write meaningful commit messages

   • Helps future debugging
   • Documents intent

5. Monitor CI actively

   • Don't "fire and forget"
   • Fix failures promptly

Next Steps

After validation passes:

1. Push branch
2. Create PR
3. Monitor CI
4. Address review feedback
5. Merge when green
6. Verify main CI stays green

References

• validation-checklist.md - Complete checklist
• merge-process.md - Detailed merge workflow
• .github/workflows/rust.yml - CI configuration
• scripts/ci/validate-cleanup.sh - Validation script