Skip to content

Commit b176347

Browse files
Copilotnpv2k1
Copilot
and
npv2k1
committed
Add comprehensive CI/CD documentation and update README
Co-authored-by: npv2k1 <[email protected]>
1 parent ccb74b3 commit b176347

File tree

2 files changed

+348
-3
lines changed

2 files changed

+348
-3
lines changed

‎README.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -194,9 +194,12 @@ For testing with in-memory database:
194194

195195
The project includes comprehensive GitHub Actions workflows:
196196

197-
- **CI**: Build, test, lint, and format checks on multiple platforms
198-
- **Security**: Weekly security audits with `cargo audit`
199-
- **Release**: Automated binary releases for Linux, macOS, and Windows
197+
- **CI** (`ci.yml`): Build, test, lint, and format checks on multiple platforms (Linux, macOS, Windows)
198+
- **Security** (`security.yml`): Weekly security audits with `cargo audit`
199+
- **Release** (`release.yml`): Automated binary releases for Linux, macOS, and Windows on version tags
200+
- **Docker** (`docker.yml`): Docker image build testing and docker-compose validation
201+
202+
All workflows run automatically on push and pull requests to ensure code quality and security.
200203

201204
## Contributing
202205

‎docs/CI-CD.md‎

Lines changed: 342 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,342 @@
1+
# CI/CD Documentation
2+
3+
This document describes the Continuous Integration and Continuous Deployment (CI/CD) workflows configured for this project.
4+
5+
## Overview
6+
7+
The project uses GitHub Actions for automated testing, building, and releasing. All workflows are located in `.github/workflows/`.
8+
9+
## Workflows
10+
11+
### 1. CI Workflow (`ci.yml`)
12+
13+
**Triggers:**
14+
- Push to `main` branch
15+
- Pull requests to `main` branch
16+
17+
**Jobs:**
18+
19+
#### Test
20+
- Runs on: Ubuntu Latest
21+
- Steps:
22+
1. Checkout code
23+
2. Install Rust stable
24+
3. Cache dependencies (Cargo registry, git, and target directory)
25+
4. Run `cargo test --verbose`
26+
27+
#### Clippy (Linter)
28+
- Runs on: Ubuntu Latest
29+
- Steps:
30+
1. Checkout code
31+
2. Install Rust stable with clippy component
32+
3. Cache dependencies
33+
4. Run `cargo clippy -- -D warnings` (fails on any warnings)
34+
35+
#### Rustfmt (Code Formatting)
36+
- Runs on: Ubuntu Latest
37+
- Steps:
38+
1. Checkout code
39+
2. Install Rust stable with rustfmt component
40+
3. Run `cargo fmt --all -- --check` (fails if code is not formatted)
41+
42+
#### Build
43+
- Runs on: Matrix of OS (Ubuntu, Windows, macOS)
44+
- Steps:
45+
1. Checkout code
46+
2. Install Rust stable
47+
3. Cache dependencies
48+
4. Run `cargo build --verbose --release`
49+
50+
**Purpose:** Ensures code quality, passes tests, follows formatting standards, and builds successfully on all target platforms.
51+
52+
### 2. Security Workflow (`security.yml`)
53+
54+
**Triggers:**
55+
- Weekly schedule (Sunday at 00:00 UTC)
56+
- Push to `main` branch
57+
- Pull requests to `main` branch
58+
59+
**Jobs:**
60+
61+
#### Security Audit
62+
- Runs on: Ubuntu Latest
63+
- Steps:
64+
1. Checkout code
65+
2. Install Rust stable
66+
3. Install `cargo-audit`
67+
4. Cache dependencies
68+
5. Run `cargo audit` to check for security vulnerabilities in dependencies
69+
70+
**Purpose:** Regularly scans dependencies for known security vulnerabilities and alerts on any issues.
71+
72+
### 3. Release Workflow (`release.yml`)
73+
74+
**Triggers:**
75+
- Push of tags matching `v*.*.*` (e.g., `v0.1.0`, `v1.2.3`)
76+
77+
**Jobs:**
78+
79+
#### Build and Release
80+
- Runs on: Matrix of OS and targets
81+
- Targets:
82+
- Linux: `x86_64-unknown-linux-gnu`
83+
- Windows: `x86_64-pc-windows-msvc`
84+
- macOS: `x86_64-apple-darwin`
85+
- Steps:
86+
1. Checkout code
87+
2. Install Rust stable with target
88+
3. Cache dependencies (per target)
89+
4. Build release binary: `cargo build --release --target <target>`
90+
5. Upload artifact with platform-specific name
91+
92+
#### Create Release
93+
- Depends on: build-and-release
94+
- Runs on: Ubuntu Latest
95+
- Steps:
96+
1. Checkout code
97+
2. Download all artifacts
98+
3. Create GitHub release with:
99+
- All platform binaries
100+
- Auto-generated release notes
101+
- Tag information
102+
103+
**Purpose:** Automatically builds and publishes release binaries for all supported platforms when a version tag is pushed.
104+
105+
**Usage:**
106+
```bash
107+
# Create a release
108+
git tag -a v0.1.0 -m "Release version 0.1.0"
109+
git push origin v0.1.0
110+
111+
# The workflow will automatically:
112+
# 1. Build binaries for Linux, macOS, and Windows
113+
# 2. Create a GitHub release
114+
# 3. Upload binaries as release assets
115+
```
116+
117+
### 4. Docker Workflow (`docker.yml`)
118+
119+
**Triggers:**
120+
- Push to `main` branch
121+
- Pull requests to `main` branch
122+
123+
**Jobs:**
124+
125+
#### Docker Build Test
126+
- Runs on: Ubuntu Latest
127+
- Steps:
128+
1. Checkout code
129+
2. Set up Docker Buildx
130+
3. Build Docker image with cache
131+
4. Test Docker image (run help command)
132+
133+
**Purpose:** Ensures Docker image builds successfully and can run basic commands.
134+
135+
#### Docker Compose Validation
136+
- Runs on: Ubuntu Latest
137+
- Steps:
138+
1. Checkout code
139+
2. Validate `docker-compose.yml` syntax
140+
141+
**Purpose:** Ensures docker-compose configuration is valid.
142+
143+
## Caching Strategy
144+
145+
All workflows use GitHub Actions caching to speed up builds:
146+
147+
```yaml
148+
path: |
149+
~/.cargo/registry
150+
~/.cargo/git
151+
target
152+
key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
153+
```
154+
155+
This caches:
156+
- Cargo package registry
157+
- Git repositories of dependencies
158+
- Build artifacts
159+
160+
The cache is invalidated when `Cargo.lock` changes (i.e., when dependencies are updated).
161+
162+
## Branch Protection
163+
164+
To ensure code quality, consider enabling branch protection rules for `main`:
165+
166+
1. **Require pull request reviews**: At least 1 approval
167+
2. **Require status checks**: All CI jobs must pass
168+
3. **Require branches to be up to date**: Prevent merge conflicts
169+
4. **Require linear history**: Keep history clean
170+
171+
## Adding New Workflows
172+
173+
### Example: Add a Coverage Workflow
174+
175+
Create `.github/workflows/coverage.yml`:
176+
177+
```yaml
178+
name: Coverage
179+
180+
on:
181+
push:
182+
branches: [ "main" ]
183+
pull_request:
184+
branches: [ "main" ]
185+
186+
jobs:
187+
coverage:
188+
runs-on: ubuntu-latest
189+
steps:
190+
- uses: actions/checkout@v4
191+
192+
- name: Install Rust
193+
uses: dtolnay/rust-toolchain@stable
194+
195+
- name: Install tarpaulin
196+
run: cargo install cargo-tarpaulin
197+
198+
- name: Generate coverage
199+
run: cargo tarpaulin --out Xml
200+
201+
- name: Upload coverage to Codecov
202+
uses: codecov/codecov-action@v3
203+
with:
204+
files: ./cobertura.xml
205+
```
206+
207+
## Best Practices
208+
209+
### 1. Keep Workflows Fast
210+
- Use caching extensively
211+
- Run jobs in parallel when possible
212+
- Use matrix builds for multiple platforms
213+
214+
### 2. Fail Fast
215+
- Use `-- -D warnings` for clippy to catch issues early
216+
- Run format checks before heavy builds
217+
- Use `--check` flags for validation-only steps
218+
219+
### 3. Security
220+
- Never commit secrets to workflows
221+
- Use GitHub Secrets for sensitive data
222+
- Regularly update dependencies with security patches
223+
- Use `cargo audit` to catch vulnerabilities
224+
225+
### 4. Versioning
226+
- Use semantic versioning (SemVer) for releases
227+
- Document breaking changes in release notes
228+
- Test thoroughly before tagging releases
229+
230+
### 5. Documentation
231+
- Update release notes automatically
232+
- Keep workflow documentation current
233+
- Document any manual release steps
234+
235+
## Troubleshooting
236+
237+
### Build Failures
238+
239+
**Problem:** Build fails on specific platform
240+
241+
**Solution:**
242+
1. Check the workflow logs for the specific error
243+
2. Test locally on that platform if possible
244+
3. Check for platform-specific dependencies
245+
4. Review recent changes that might affect that platform
246+
247+
### Cache Issues
248+
249+
**Problem:** Builds are slower than expected
250+
251+
**Solution:**
252+
1. Check if cache is being hit (look for "Cache restored" in logs)
253+
2. Verify cache key includes `Cargo.lock` hash
254+
3. Clear cache if corrupted (manually delete in GitHub UI)
255+
256+
### Release Failures
257+
258+
**Problem:** Release workflow fails to create release
259+
260+
**Solution:**
261+
1. Verify tag follows `v*.*.*` format
262+
2. Check `GITHUB_TOKEN` permissions
263+
3. Ensure all build jobs completed successfully
264+
4. Verify artifact names match expected patterns
265+
266+
### Security Audit Failures
267+
268+
**Problem:** `cargo audit` finds vulnerabilities
269+
270+
**Solution:**
271+
1. Review the security advisory
272+
2. Update affected dependencies: `cargo update`
273+
3. If no fix available, consider:
274+
- Finding alternative dependency
275+
- Waiting for upstream fix
276+
- Documenting known issue
277+
278+
## Monitoring
279+
280+
### Workflow Status
281+
282+
Monitor workflow runs:
283+
- GitHub repository → Actions tab
284+
- View logs for failed runs
285+
- Check timing to optimize performance
286+
287+
### Notifications
288+
289+
Enable notifications for:
290+
- Failed workflow runs on main branch
291+
- Security vulnerabilities
292+
- Failed releases
293+
294+
Configure in: GitHub Settings → Notifications
295+
296+
## Local Testing
297+
298+
Before pushing, test locally:
299+
300+
```bash
301+
# Run all checks
302+
make all
303+
304+
# Or individually
305+
cargo fmt --check
306+
cargo clippy -- -D warnings
307+
cargo test
308+
cargo build --release
309+
310+
# Test Docker
311+
docker build -t template-rust:test .
312+
docker run --rm template-rust:test --help
313+
314+
# Validate docker-compose
315+
docker compose config
316+
```
317+
318+
## Future Improvements
319+
320+
Consider adding:
321+
322+
1. **Code Coverage**: Track test coverage with codecov or coveralls
323+
2. **Benchmarking**: Automated performance regression testing
324+
3. **Deploy to Registry**: Publish Docker images to GitHub Container Registry
325+
4. **Nightly Builds**: Test against Rust nightly to catch future issues
326+
5. **Dependency Updates**: Automated PRs for dependency updates (Dependabot)
327+
6. **Documentation Deployment**: Auto-deploy docs to GitHub Pages
328+
329+
## Resources
330+
331+
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
332+
- [Rust CI/CD Guide](https://doc.rust-lang.org/cargo/guide/continuous-integration.html)
333+
- [Actions for Rust](https://github.com/actions-rs)
334+
- [Semantic Versioning](https://semver.org/)
335+
336+
## Questions or Issues
337+
338+
If you have questions about the CI/CD setup:
339+
1. Check this documentation
340+
2. Review workflow files in `.github/workflows/`
341+
3. Check workflow run logs for details
342+
4. Open an issue for discussion

0 commit comments

Comments
 (0)