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:

Format Check
- Runs cargo fmt -- --check
- Fast fail if unformatted
Clippy
- Runs with -D warnings
- Zero warnings required
Build Matrix
- Minimal features
- All features
- Multiple Rust versions (stable, nightly)
Test Matrix
- Linux, macOS, Windows
- Unit + integration tests
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%:

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

Release Process

Pre-Release Checklist

All tests pass
```
cargo test --all-features
```
Benchmarks run
```
cargo bench --features=benchmarks
```
Documentation builds
```
cargo doc --no-deps --all-features
```
Examples work
```
cargo run --example basic_usage
```

Update CHANGELOG.md

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

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

Validate locally before pushing
- Saves CI resources
- Faster feedback loop
Fix clippy warnings immediately
- Don't accumulate tech debt
- Easier to fix in context
Keep PRs small
- Easier to review
- Easier to revert if needed
Write meaningful commit messages
- Helps future debugging
- Documents intent
Monitor CI actively
- Don't "fire and forget"
- Fix failures promptly

Next Steps

After validation passes:

Push branch
Create PR
Monitor CI
Address review feedback
Merge when green
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