===================================================================
CI/CD Pipeline Recommended Changes (Minimal - Tier 2)
===================================================================
File: .github/workflows/ci.yml
CHANGE 1: Add Bevy Headless Mode Environment Variables
Location: Lines 10-12 (env section)
Effort: 2 minutes
Priority: Medium
@@ -10,6 +10,8 @@
env:
CARGO_TERM_COLOR: always
RUST_BACKTRACE: 1
+ # Bevy headless rendering configuration for CI
+ WGPU_BACKEND: vk
jobs:
# Fast check job - runs first to fail fast
RATIONALE:
- Ensures Bevy tests run in headless mode
- Prevents graphics subsystem initialization attempts
- Non-blocking addition to environment
- Safe: only affects optional feature tests
===================================================================
CHANGE 2: Add Test Timeout - Library Tests
Location: Line 87 (test job, library tests step)
Effort: 1 minute
Priority: High
@@ -85,7 +85,7 @@
- name: Run library tests
- run: cargo test --lib --verbose
+ run: timeout 300 cargo test --lib --verbose
RATIONALE:
- Prevents hanging tests from blocking pipeline indefinitely
- 300 seconds = 5 minutes (plenty of headroom, current avg ~30-60s)
- Fails clearly if test hangs (timeout error in logs)
- Non-breaking: tests complete in well under 5 minutes currently
===================================================================
CHANGE 3: Add Test Timeout - Integration Tests
Location: Line 90 (test job, integration tests step)
Effort: 1 minute
Priority: High
@@ -88,7 +88,7 @@
- name: Run integration tests
- run: cargo test --test '*' --verbose
+ run: timeout 300 cargo test --test '*' --verbose
RATIONALE:
- Same as Change 2, applies to integration test suite
- Current integration tests take ~60-90 seconds
- Timeout of 300s provides ample margin
===================================================================
CHANGE 4: Add Test Timeout - Doc Tests
Location: Line 93 (test job, doc tests step)
Effort: 1 minute
Priority: High
@@ -91,7 +91,7 @@
- name: Run doc tests
- run: cargo test --doc --verbose
+ run: timeout 300 cargo test --doc --verbose
RATIONALE:
- Completes the safety net for all test jobs
- Doc tests typically fastest (~10-30 seconds)
- Consistency across all test steps
===================================================================
CHANGE 5: Fix MSRV Version Alignment
Location: Line 242 (msrv job)
Effort: 1 minute
Priority: High
@@ -239,8 +239,8 @@
- name: Setup Rust 1.70
+ - name: Setup Rust 1.75 (MSRV)
uses: dtolnay/rust-toolchain@master
with:
- toolchain: "1.70"
+ toolchain: "1.75"
RATIONALE:
- Cargo.toml declares: rust-version = "1.75"
- CI currently tests against 1.70 (older than declared)
- If code uses 1.75+ features, CI would pass but MSRV claim would be false
- Fix: Test against declared version to verify claim
===================================================================
OPTIONAL ENHANCEMENT: Improve Feature Test Timeouts
Location: Line 131 (feature-tests job)
Effort: 1 minute
Priority: Medium
Status: OPTIONAL (good-to-have)
@@ -129,7 +129,7 @@
- name: Test with features ${{ matrix.features }}
- run: cargo test ${{ matrix.features }} --verbose
+ run: timeout 300 cargo test ${{ matrix.features }} --verbose
RATIONALE:
- Consistency with other test jobs
- Each feature combination tested with same timeout
- Prevents one slow feature combination from blocking others
===================================================================
OPTIONAL ENHANCEMENT: Improve Coverage Report
Location: Lines 161-163 (coverage job)
Effort: 2 minutes
Priority: Low
Status: OPTIONAL (nice-to-have)
@@ -160,7 +160,12 @@
- name: Generate code coverage
run: |
- cargo tarpaulin --verbose --all-features --workspace --timeout 300 --out xml --output-dir coverage
+ cargo tarpaulin \
+ --verbose \
+ --all-features \
+ --workspace \
+ --timeout 300 \
+ --exclude-files tests/* \
+ --out xml \
+ --output-dir coverage
RATIONALE:
- --exclude-files tests/* excludes test code from coverage metrics
- Focus coverage on application code, not test infrastructure
- Makes coverage metrics more meaningful
- Multiline format improves readability
===================================================================
SUMMARY OF CHANGES
Minimal Path (Must-Have):
- CHANGE 2, 3, 4: Add test timeouts (3 lines changed) ✅ HIGH PRIORITY
- CHANGE 5: Fix MSRV version (1 line changed) ✅ HIGH PRIORITY
Total effort: 8 minutes
Total lines changed: 4
Conservative Path (Nice-to-Have):
- Plus CHANGE 1: Add Bevy headless mode (1 line added) ⚠️ MEDIUM PRIORITY
- Plus OPTIONAL Feature timeouts (1 line changed) ⚠️ MEDIUM PRIORITY
Total effort: 10-12 minutes
Total lines changed: 6
Enhanced Path (Best-Practice):
- All of above plus Coverage improvement ✅ LOW PRIORITY
Total effort: 12-15 minutes
Total lines changed: 13
===================================================================
IMPLEMENTATION CHECKLIST
[ ] Read this document (5 minutes)
[ ] Back up original: cp .github/workflows/ci.yml .github/workflows/ci.yml.backup
[ ] Make CHANGE 5 first (MSRV fix - easiest)
[ ] Make CHANGES 2-4 (test timeouts - low risk)
[ ] Make CHANGE 1 (Bevy headless - optional)
[ ] Make OPTIONAL changes (improvements - optional)
[ ] Verify syntax: yamllint .github/workflows/ci.yml
[ ] Test locally: cargo check --all-features
[ ] Commit changes with clear message
[ ] Push to branch and create PR
[ ] Monitor CI run on branch
[ ] Merge to main once CI passes
===================================================================
TESTING YOUR CHANGES
Before committing:
1. Syntax check:
yamllint .github/workflows/ci.yml
2. Line count (should increase by 4-13 lines):
wc -l .github/workflows/ci.yml
3. Verify timeout present:
grep -c "timeout 300" .github/workflows/ci.yml
# Should output 4 or 5 depending on optional changes
4. Verify MSRV version:
grep "1.75" .github/workflows/ci.yml
# Should show 2+ matches
5. Verify Cargo.toml matches:
grep "rust-version" Cargo.toml
# Should show: rust-version = "1.75"
===================================================================
ROLLBACK INSTRUCTIONS
If you need to revert:
cp .github/workflows/ci.yml.backup .github/workflows/ci.yml
git checkout .github/workflows/ci.yml
===================================================================
VALIDATION AFTER MERGE
Once merged to main, verify:
[ ] First CI run completes successfully
[ ] All jobs pass (check, test, features, coverage, audit, examples, msrv)
[ ] No timeout errors in logs
[ ] Coverage report generated and uploaded to codecov
[ ] MSRV job succeeds with 1.75
[ ] Job durations unchanged (~15-20 min total)
===================================================================
EXPECTED IMPACT
No behavior changes - only adding safety nets.
Before:
- 15-20 min execution time
- 44+ tests passing
- 95% parallel execution
After:
- 15-20 min execution time (SAME)
- 44+ tests passing (SAME)
- 95% parallel execution (SAME)
- Tests have timeout safety net (NEW)
- MSRV properly aligned (FIXED)
- Bevy runs in headless mode (IMPROVED)
Risk level: VERY LOW (conservative changes only)
===================================================================
QUESTIONS?
See full documentation:
- CI_VERIFICATION_REPORT.md - Comprehensive technical analysis
- CI_IMPLEMENTATION_GUIDE.md - Step-by-step implementation guide
- CI_ANALYSIS_SUMMARY.md - Executive summary
- CI_QUICK_REFERENCE.md - One-page reference
===================================================================
Generated: November 20, 2025
Status: RECOMMENDED FOR IMPLEMENTATION
Confidence: 95%
===================================================================