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

bash

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

Manual Step-by-Step

1. Format Code

bash

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

2. Clippy (Zero Warnings)

bash

# 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)

bash

# 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)

bash

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

Must succeed - tests complete build.

5. Run Tests (Library)

bash

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

Track test count - should not decrease unexpectedly.

6. Run Integration Tests

bash

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

Must pass - validates end-to-end functionality.

7. Coverage Check

bash

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

Target: ≥90% coverage (PRD requirement)

Feature Flag Testing

M1 Feature Gates

Core reading (minimal):

bash

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

With benchmarks:

bash

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

All features:

bash

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

Validate Feature Combinations

bash

# 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

bash

# 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

bash

# 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):

bash

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

Merge commit (for feature branches):

bash

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

Rebase (for clean history):

bash

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

Commit Message Format

code

<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:

code

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:

bash

# Unused imports
cargo clippy --fix

# Unnecessary clones
# Review each and remove if safe

# Dead code warnings
# Expected for cleanup issues - document

Test Failures

Debugging:

bash

# 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:

bash

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

Dependency issues:

bash

# 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
bash
```
cargo test --all-features
```
•
Benchmarks run
bash
```
cargo bench --features=benchmarks
```
•
Documentation builds
bash
```
cargo doc --no-deps --all-features
```
•
Examples work
bash
```
cargo run --example basic_usage
```

•

Update CHANGELOG.md

markdown

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

•

Update version

toml

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

Creating Release

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# .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

bash

# .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:

bash

# 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:

bash

# 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