Merge remote-tracking branch 'origin' into fix-encode-decode

Author: happy-v587

.github/CI_IMPROVEMENTS.md

@@ -0,0 +1,211 @@
+# CI/CD Improvements
+
+This document summarizes the CI/CD improvements added to the project.
+
+## 🎯 Overview
+
+This PR adds missing CI/CD capabilities while preserving the existing, well-functioning CI pipeline. We only add what's truly missing, avoiding duplication.
+
+## 📦 What's New
+
+### 1. CodeQL Security Analysis (`codeql.yml`)
+
+**Purpose:** Automated security vulnerability scanning
+
+**Features:**
+- Runs on push to main/develop and PRs
+- Weekly scheduled scans (every Monday)
+- Uses security-and-quality query suite
+- Results appear in GitHub Security tab
+
+**Benefits:**
+- Early detection of security vulnerabilities
+- Automated security reports
+- Compliance with security best practices
+
+### 2. Docker Multi-arch Publishing (`docker-publish.yml`)
+
+**Purpose:** Publish Docker images to GitHub Container Registry
+
+**Status:** ⚠️ Requires Dockerfile to be added to the project
+
+**Features:**
+- Multi-architecture support (amd64/arm64)
+- Triggered on GitHub releases
+- Smart semantic versioning tags
+- No external secrets needed (uses GITHUB_TOKEN)
+
+**Prerequisites:**
+- Add a `Dockerfile` to the project root
+- Or specify the Dockerfile path in the workflow
+
+**Image Tags:**
+- `ghcr.io/owner/repo:v1.2.3` (full version)
+- `ghcr.io/owner/repo:1.2` (minor version)
+- `ghcr.io/owner/repo:1` (major version)
+- `ghcr.io/owner/repo:latest` (stable releases only)
+
+### 3. Automated Release (`release.yml`)
+
+**Purpose:** Build and publish multi-platform binaries
+
+**Features:**
+- Multi-platform builds (Linux amd64/arm64, macOS Intel/Apple Silicon, Windows)
+- Cross-compilation support
+- SHA256 checksums for all artifacts
+- Automated release notes generation
+
+**Artifacts:**
+- Compressed binaries (tar.gz for Unix, zip for Windows)
+- SHA256 checksums
+- README and LICENSE included
+
+### 4. Benchmark Tracking (`benchmark.yml`)
+
+**Purpose:** Track performance over time
+
+**Features:**
+- Runs on every push to main
+- Stores benchmark history
+- Alerts on 150%+ performance regressions
+- Automatic PR comments on regressions
+
+### 5. Enhanced Dependabot (`dependabot.yml`)
+
+**Improvements:**
+- Added Cargo ecosystem support
+- Grouped patch updates to reduce PR noise
+- Better labeling by ecosystem
+
+### 6. Improved Issue Templates
+
+**Enhancements:**
+- Duplicate check requirement
+- Structured environment information
+- Rust-specific fields
+- Better organization with sections
+
+### 7. Pull Request Template (`pull_request_template.md`)
+
+**New Features:**
+- Comprehensive checklist
+- Change type classification
+- Testing section
+- Security awareness prompts
+
+### 8. Contributing Guidelines (`CONTRIBUTING.md`)
+
+**New Document:**
+- Development setup instructions
+- Commit message conventions (Conventional Commits)
+- Code style guidelines
+- Testing best practices
+- PR submission guidelines
+
+## 📊 What We Kept (Already Excellent)
+
+The existing `ci.yml` already has:
+- ✅ Multi-platform testing (Linux/macOS/Windows)
+- ✅ Sanitizers (ASAN/LSAN/TSAN)
+- ✅ Docker build testing
+- ✅ Static analysis (cargo-audit, cargo-deny)
+- ✅ Integration tests
+- ✅ sccache for faster builds
+
+We intentionally did NOT duplicate these features.
+
+## 🎯 Design Principles
+
+1. **No Duplication:** Don't recreate what already works
+2. **Additive Only:** Only add truly missing features
+3. **Stability First:** Preserve existing stable workflows
+4. **Clear Separation:** New workflows have distinct purposes
+
+## 📝 File Changes Summary
+
+### Added Files
+- `.github/workflows/codeql.yml` - Security scanning
+- `.github/workflows/docker-publish.yml` - Docker publishing
+- `.github/workflows/release.yml` - Release automation
+- `.github/workflows/benchmark.yml` - Performance tracking
+- `.github/pull_request_template.md` - PR template
+- `CONTRIBUTING.md` - Contributing guide
+
+### Modified Files
+- `.github/dependabot.yml` - Added Cargo support
+- `.github/ISSUE_TEMPLATE/bug_report.yml` - Enhanced structure
+- `.gitignore` - Exclude reference materials
+
+### Removed Files
+None - all existing workflows preserved
+
+## 🚀 Usage
+
+### For Releases
+
+1. Create and push a tag:
+   ```bash
+   git tag v1.0.0
+   git push --tags
+   ```
+
+2. The release workflow automatically:
+   - Builds binaries for all platforms
+   - Creates GitHub release
+   - Uploads artifacts with checksums
+
+3. The docker-publish workflow automatically:
+   - Builds multi-arch images
+   - Publishes to GHCR
+   - Tags with semantic versions
+
+### For Security
+
+- CodeQL runs automatically on PRs and weekly
+- View results in the Security tab
+- No configuration needed
+
+### For Benchmarks
+
+- Runs automatically on main branch
+- View history in GitHub Pages (if enabled)
+- Alerts appear as PR comments
+
+## 🔧 Configuration
+
+### Docker Publishing
+No additional configuration needed - uses `GITHUB_TOKEN` automatically.
+
+### Benchmarks (Optional)
+Enable GitHub Pages in repository settings for benchmark visualization.
+
+### Releases
+Just push a tag - everything else is automatic.
+
+## 📚 Best Practices Adopted
+
+1. **Minimal Permissions:** Each workflow requests only what it needs
+2. **Fail Gracefully:** Non-critical checks don't block development
+3. **Clear Naming:** Workflow names clearly indicate purpose
+4. **Artifact Management:** Appropriate retention periods
+5. **Cache Efficiency:** Reuse existing cache strategies
+6. **Platform-Specific Steps:** Conditional execution where needed
+
+## 🔮 Future Enhancements
+
+Potential additions (not included to keep PR focused):
+- Code coverage reporting
+- Fuzzing for security-critical code
+- Nightly builds against Rust nightly
+- Performance profiling with flamegraphs
+
+## 📖 References
+
+- [GitHub Actions Best Practices](https://docs.github.com/en/actions/learn-github-actions/best-practices-for-workflows)
+- [Rust CI Best Practices](https://doc.rust-lang.org/cargo/guide/continuous-integration.html)
+- [Conventional Commits](https://www.conventionalcommits.org/)
+- [Semantic Versioning](https://semver.org/)
+
+## 🙏 Acknowledgments
+
+Inspired by best practices from the QuantClaw project, adapted for the Rust/Cargo ecosystem.