Skip to content

Commit 34ddd26

Browse files
Copilotnpv2k1
Copilot
and
npv2k1
committed
docs: add comprehensive CI/CD documentation
Co-authored-by: npv2k1 <73846954+npv2k1@users.noreply.github.com>
1 parent 232cf11 commit 34ddd26

1 file changed

Lines changed: 256 additions & 0 deletions

File tree

‎.github/CI_CD_DOCUMENTATION.md‎

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
# CI/CD Documentation
2+
3+
## Overview
4+
5+
This Electron template includes a comprehensive CI/CD setup using GitHub Actions. The workflows are designed to automate testing, building, and releasing across multiple platforms.
6+
7+
## Workflows
8+
9+
### 1. CI Workflow (`ci.yml`)
10+
11+
**Triggers:**
12+
- Push to `main` or `develop` branches
13+
- Pull requests to `main` or `develop` branches
14+
- Manual trigger via workflow dispatch
15+
16+
**What it does:**
17+
- Runs on Ubuntu, Windows, and macOS
18+
- Tests with Node.js 18.x and 20.x
19+
- Installs dependencies with caching
20+
- Performs TypeScript type checking
21+
- Builds the project
22+
- Builds the Electron application
23+
- Uploads build artifacts
24+
25+
**Usage:** Automatically runs on every push/PR. No manual intervention needed.
26+
27+
### 2. Release Workflow (`release.yml`)
28+
29+
**Triggers:**
30+
- Push of version tags (e.g., `v1.0.0`)
31+
- Manual trigger with version input
32+
33+
**What it does:**
34+
- Builds for Windows (NSIS installer)
35+
- Builds for macOS (DMG)
36+
- Builds for Linux (AppImage, deb)
37+
- Creates a GitHub release
38+
- Uploads binaries as release assets
39+
- Generates release notes automatically
40+
41+
**Usage:**
42+
```bash
43+
# Create a new release
44+
git tag v1.0.0
45+
git push origin v1.0.0
46+
47+
# Or use manual dispatch from GitHub Actions tab
48+
```
49+
50+
### 3. PR Check Workflow (`pr-check.yml`)
51+
52+
**Triggers:**
53+
- Pull request opened, synchronized, or reopened
54+
55+
**What it does:**
56+
- TypeScript type checking
57+
- Build verification
58+
- PR size warnings (alerts if PR has >1000 changes)
59+
60+
**Usage:** Automatically runs on PR creation/updates.
61+
62+
### 4. Code Quality Workflow (`quality.yml`)
63+
64+
**Triggers:**
65+
- Push to `main` or `develop` branches
66+
- Pull requests to `main` or `develop` branches
67+
- Weekly schedule (Mondays at 00:00 UTC)
68+
69+
**What it does:**
70+
- TypeScript type checking
71+
- Checks for console.log statements
72+
- npm security audit
73+
- Bundle size analysis
74+
75+
**Usage:** Runs automatically on schedule and with pushes/PRs.
76+
77+
### 5. Stale Workflow (`stale.yml`)
78+
79+
**Triggers:**
80+
- Daily schedule (00:00 UTC)
81+
- Manual trigger via workflow dispatch
82+
83+
**What it does:**
84+
- Marks issues as stale after 60 days of inactivity
85+
- Marks PRs as stale after 30 days of inactivity
86+
- Closes stale issues/PRs after 7 additional days
87+
- Respects exemption labels (pinned, security, etc.)
88+
89+
**Usage:** Runs automatically daily.
90+
91+
## Dependabot
92+
93+
**Configuration:** `.github/dependabot.yml`
94+
95+
**Updates:**
96+
- npm packages: Weekly
97+
- GitHub Actions: Weekly
98+
99+
**Labels:** `dependencies`, `automated`, `github-actions`
100+
101+
## Issue Templates
102+
103+
### Bug Report (`bug_report.yml`)
104+
Structured form for reporting bugs with:
105+
- Description
106+
- Steps to reproduce
107+
- Expected vs actual behavior
108+
- Environment details (OS, Node.js version)
109+
110+
### Feature Request (`feature_request.yml`)
111+
Structured form for suggesting features with:
112+
- Problem statement
113+
- Proposed solution
114+
- Alternatives considered
115+
- Implementation complexity
116+
117+
## Pull Request Template
118+
119+
**Location:** `.github/PULL_REQUEST_TEMPLATE.md`
120+
121+
**Includes:**
122+
- Description
123+
- Type of change
124+
- Related issues
125+
- Changes made
126+
- Testing checklist
127+
- Review checklist
128+
129+
## Security
130+
131+
**Security Policy:** `SECURITY.md`
132+
133+
**Best Practices:**
134+
- npm audit runs in quality workflow
135+
- Dependabot monitors dependencies
136+
- Security label exempts issues from stale bot
137+
138+
## Contributing
139+
140+
**Contributing Guide:** `CONTRIBUTING.md`
141+
142+
**Includes:**
143+
- Development setup
144+
- Code quality guidelines
145+
- Commit message conventions
146+
- PR process
147+
- Building instructions
148+
- Release process
149+
150+
## Badges
151+
152+
The README includes badges for:
153+
- CI workflow status
154+
- Release workflow status
155+
- Code Quality workflow status
156+
- MIT License
157+
158+
## Release Process
159+
160+
### Automated Release (Recommended)
161+
162+
1. Update version in `package.json`
163+
2. Update `CHANGELOG.md`
164+
3. Commit changes
165+
4. Create and push tag:
166+
```bash
167+
git tag v1.0.0
168+
git push origin v1.0.0
169+
```
170+
5. GitHub Actions will automatically:
171+
- Build for all platforms
172+
- Create GitHub release
173+
- Upload binaries
174+
- Generate release notes
175+
176+
### Manual Release
177+
178+
1. Go to Actions tab on GitHub
179+
2. Select "Release" workflow
180+
3. Click "Run workflow"
181+
4. Enter version (e.g., v1.0.0)
182+
5. Click "Run workflow" button
183+
184+
## Local Testing
185+
186+
Before pushing changes, test locally:
187+
188+
```bash
189+
# Install dependencies
190+
npm ci
191+
192+
# Type check
193+
npx tsc --noEmit
194+
195+
# Build
196+
npm run build
197+
198+
# Test Electron build (will take longer)
199+
npm run electron:build
200+
```
201+
202+
## Troubleshooting
203+
204+
### CI Fails on Type Checking
205+
- Run `npx tsc --noEmit` locally
206+
- Fix type errors
207+
- Commit and push
208+
209+
### Build Fails
210+
- Check `vite.config.ts` configuration
211+
- Ensure all dependencies are installed
212+
- Check for missing files
213+
214+
### Release Fails
215+
- Ensure tag follows semantic versioning (v1.0.0)
216+
- Check `package.json` version matches tag
217+
- Verify `electron-builder` configuration in `package.json`
218+
219+
### Artifacts Not Uploaded
220+
- Check workflow permissions
221+
- Verify artifact paths in workflow
222+
- Ensure build completed successfully
223+
224+
## Maintenance
225+
226+
### Updating Workflows
227+
228+
1. Edit workflow files in `.github/workflows/`
229+
2. Test locally if possible
230+
3. Commit and push to a feature branch
231+
4. Create PR to verify changes
232+
5. Merge when CI passes
233+
234+
### Updating Dependencies
235+
236+
- Dependabot will create PRs automatically
237+
- Review changes in PR
238+
- Merge if CI passes
239+
- Monitor for breaking changes
240+
241+
## Best Practices
242+
243+
1. **Always test locally** before pushing
244+
2. **Use semantic versioning** for releases
245+
3. **Update CHANGELOG.md** for each release
246+
4. **Keep dependencies updated** via Dependabot
247+
5. **Monitor CI failures** and fix promptly
248+
6. **Review Dependabot PRs** regularly
249+
7. **Keep documentation updated** with changes
250+
251+
## Resources
252+
253+
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
254+
- [Electron Builder Documentation](https://www.electron.build/)
255+
- [Semantic Versioning](https://semver.org/)
256+
- [Keep a Changelog](https://keepachangelog.com/)

0 commit comments

Comments
 (0)