| name | CI/CD Validation & Merge Workflow |
| description | Pre-push validation checklist (cargo fmt, clippy with zero warnings, feature flag testing, test suite), CI monitoring, merge process, and release quality gates. Use when preparing to push code, validating changes before PR, running CI checks, merging PRs, or preparing releases. |
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
./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)
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)
cargo build --package cqlite-core --no-default-features --features=all-compression
Must succeed - tests feature gate correctness.
4. Build (All Features)
cargo build --package cqlite-core --all-features
Must succeed - tests complete build.
5. Run Tests (Library)
cargo test --package cqlite-core --lib --all-features
Track test count - should not decrease unexpectedly.
6. Run Integration Tests
cargo test --test '*'
Must pass - validates end-to-end functionality.
7. Coverage Check
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
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
gh run list --branch <branch-name> --limit 5
gh run view <run-id>
gh run watch <run-id>
Check Failures
gh run view <run-id> --log
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 featurefix: Bug fixrefactor: Code refactoringperf: Performance improvementtest: Test additions/changesdocs: Documentationstyle: Formattingchore: Build/toolingcleanup: 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:
cargo clippy --fix
Test Failures
Debugging:
cargo test --test test_name -- --nocapture
RUST_BACKTRACE=1 cargo test test_name
RUST_LOG=debug cargo test test_name
Build Failures
Feature flag issues:
[features]
default = ["all-compression"]
all-compression = ["lz4", "snap", "flate2"]
benchmarks = []
Dependency issues:
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
[package]
version = "0.1.0"
Creating Release
git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0
gh release create v0.1.0 \
--title "v0.1.0 - Initial Release" \
--notes-file RELEASE_NOTES.md \
--draft
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
cargo fmt --all
cargo clippy --package cqlite-core --lib --all-features -- -D warnings
cargo test --package cqlite-core --lib
git push origin feature/my-branch
Scenario 2: CI Failure Investigation
gh run view --log
cargo test --package cqlite-core --lib --features=all-compression
git commit --amend
git push --force-with-lease origin feature/my-branch
Scenario 3: Merge Blocked by Coverage
cargo tarpaulin --out Html
open tarpaulin-report.html
Automation
Pre-Commit Hook
set -e
echo "Running pre-commit checks..."
cargo fmt --all -- --check
cargo clippy --package cqlite-core --lib --all-features -- -D warnings
cargo test --package cqlite-core --lib
echo "Pre-commit checks passed!"
Pre-Push Hook
set -e
echo "Running pre-push 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:
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:
rustc --version
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
