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/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. Run Property Tests

bash

# Run property-based tests
cargo test --package property-tests

Must pass - validates edge cases.

8. 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
Property Tests
- Runs extended property test suite
- Timeout: 10 minutes

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

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

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/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/validate-cleanup.sh - Validation script

Search AI Tools

Install this agent skill to your Project

SKILL.md

CI/CD Validation & Merge Workflow

When to Use This Skill

Pre-Push Validation Checklist

Quick Validation

Manual Step-by-Step

1. Format Code

2. Clippy (Zero Warnings)

3. Build (Minimal Features)

4. Build (All Features)

5. Run Tests (Library)

6. Run Integration Tests

7. Run Property Tests

8. Coverage Check

Feature Flag Testing

M1 Feature Gates

Validate Feature Combinations

CI Pipeline

GitHub Actions Workflow

Monitoring CI

View Status

Check Failures

Merge Process

Prerequisites

Merge Methods

Commit Message Format

Error Handling

Clippy Failures

Test Failures

Build Failures

Coverage Failures

Release Process

Pre-Release Checklist

Creating Release

PRD Alignment

Common Scenarios

Scenario 1: Pre-Push Validation

Scenario 2: CI Failure Investigation

Scenario 3: Merge Blocked by Coverage

Automation

Pre-Commit Hook

Pre-Push Hook

Troubleshooting

Tests Pass Locally, Fail in CI

Clippy Different Results Locally vs CI

Coverage Unstable

Best Practices

Next Steps

References