Skip to content

Commit fe18325

Browse files
the78molethe78mole
authored
Add GitHub Actions workflows for PR checks and hardware release (#14)
🛠 GitHub Actions & KiCad Automation Updates - CI/CD Workflows: Added pr-check.yml and release.yml for KM217-WiFi and ETH_W5500 with build, validation, and artifact export. - Optimierung: Build-Skripte prüfen auf Änderungen seit letztem Release und überspringen unnötige Builds. - Revision Handling: * Automatische Revisionserkennung für JSON, S-Expression und XML * PR-spezifische Revisionen im Format 1.2.3-pr42 - Versionierung: Semantic Versioning + PR-Kontext in Revisionsupdates integriert. - PR-Checks: Workflow erkennt geänderte Projekte und aktualisiert nur dort die Revision. - Textvariablen: KiCad-Textfelder werden mit Git-Tags (REVISION) und Datum (CREATION_DATE) automatisch gefüllt. - Synchronisierung: Neue Scripts sync-kicad-projects.sh & update-kicad-text-variables.sh für konsistente Titelblöcke. - Fehlerbehebung: Fix für fehlende oder falsch platzierte Revisionsdateien in verschachtelten Projekten. - Skripte: Alle Shell-Skripte jetzt ausführbar, robustes Logging und Fehlerhandling. - Matrixstruktur: Workflows auf neue Projektmatrix umgestellt für klarere Abläufe und gezieltes Laden.
1 parent e0594a2 commit fe18325

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+104478
-99544
lines changed

‎.github/WORKFLOW_USAGE.md

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# GitHub Actions Workflow Usage
2+
3+
## 📋 Overview
4+
5+
This repository contains a GitHub Actions workflow for automated KiCad hardware builds and documentation generation.
6+
7+
## 🔧 Workflow: `pr-check.yml`
8+
9+
### What it does:
10+
- **Hardware Build & Export**: Exports KiCad files to production-ready formats
11+
- **Documentation Build**: Validates and processes documentation files
12+
- **PR Summary**: Generates automated PR comments with build results
13+
14+
### Jobs:
15+
16+
#### 1. 🔧 Hardware Build & Export
17+
- Validates KiCad project files
18+
- Exports Gerber files for PCB manufacturing
19+
- Generates drill files
20+
- Creates PDF documentation (schematics and PCB layouts)
21+
- Exports SVG assembly diagrams
22+
- Generates 3D STEP models
23+
- Creates production summary
24+
- Uploads all artifacts
25+
26+
#### 2. 📚 Documentation Build
27+
- Validates Markdown documentation
28+
- Builds AsciiDoc files (if present)
29+
- Generates LaTeX PDFs (if present)
30+
- Checks for broken links
31+
- Creates documentation statistics
32+
- Uploads documentation artifacts
33+
34+
#### 3. 📋 PR Summary (PR only)
35+
- Downloads artifacts from previous jobs
36+
- Generates comprehensive PR summary
37+
- Comments results on Pull Request
38+
39+
## 🚀 Usage
40+
41+
### GitHub Actions (Automatic)
42+
The workflow runs automatically on:
43+
- Pull Requests to `main` or `develop` branches
44+
- Pushes to `main` branch
45+
- Changes to:
46+
- `KM217-WiFi/**` (hardware files)
47+
- `DOC/**` (documentation)
48+
- `.github/workflows/pr-check.yml` (workflow itself)
49+
50+
### Local Testing with `act`
51+
52+
#### Prerequisites
53+
```bash
54+
# Install act (GitHub Actions runner)
55+
# macOS
56+
brew install act
57+
58+
# Linux
59+
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
60+
61+
# Or download from: https://github.com/nektos/act/releases
62+
```
63+
64+
#### Run Local Tests
65+
```bash
66+
# Test hardware build only
67+
act -j hardware-build --artifact-server-path /tmp/artifacts
68+
69+
# Test documentation build only
70+
act -j documentation-build --artifact-server-path /tmp/artifacts
71+
72+
# Test complete workflow (excluding PR comments)
73+
act --artifact-server-path /tmp/artifacts
74+
75+
# Use specific Docker platform (if needed)
76+
act -j hardware-build --artifact-server-path /tmp/artifacts --container-architecture linux/amd64
77+
```
78+
79+
#### Local Artifacts
80+
When using `act`, artifacts are stored locally:
81+
- **Location**: `/tmp/artifacts/[run-id]/[artifact-name]/`
82+
- **Hardware exports**: `/tmp/artifacts/*/km217-wifi-hardware-exports/`
83+
- **Documentation**: `/tmp/artifacts/*/km217-wifi-documentation/`
84+
85+
#### Extract Artifacts from Container
86+
```bash
87+
# Copy artifacts from act container to host
88+
docker cp $(docker ps -lq):/tmp/artifacts/ ./local-artifacts/
89+
```
90+
91+
## 📦 Generated Artifacts
92+
93+
### Hardware Exports (`km217-wifi-hardware-exports`)
94+
- **Gerber Files**: `Export/Gerbers/` - PCB manufacturing files
95+
- **Drill Files**: `Export/Drill/` - Drill hole information
96+
- **PDFs**: `Export/PDF/` - Schematics and PCB layout documentation
97+
- **Images**: `Export/Images/` - SVG assembly diagrams
98+
- **3D Models**: `Export/3D/` - STEP files for 3D visualization
99+
- **Summary**: `Export/PRODUCTION_SUMMARY.md` - Complete file overview
100+
101+
### Documentation (`km217-wifi-documentation`)
102+
- All files from `DOC/` directory
103+
- Generated HTML/PDF files (if applicable)
104+
- Documentation statistics
105+
106+
## 🔧 Customization
107+
108+
### Modify KiCad Export Settings
109+
Edit the workflow file `.github/workflows/pr-check.yml`:
110+
111+
```yaml
112+
# Example: Add more PCB layers
113+
--layers "F.Cu,B.Cu,In1.Cu,F.Paste,B.Paste,F.Silkscreen,B.Silkscreen,F.Mask,B.Mask,Edge.Cuts"
114+
115+
# Example: Change precision
116+
--precision 5 # or 6
117+
```
118+
119+
### Add Custom Validation
120+
Add custom steps in the workflow:
121+
122+
```yaml
123+
- name: 🔍 Custom Validation
124+
run: |
125+
echo "Running custom validation..."
126+
# Your custom validation logic here
127+
```
128+
129+
## 🐛 Troubleshooting
130+
131+
### Common Issues
132+
133+
1. **Missing 3D Models**: The STEP export shows warnings about missing 3D models. This is normal and doesn't affect the PCB manufacturing files.
134+
135+
2. **ImageMagick not available**: PNG conversion is skipped. SVG files are still generated.
136+
137+
3. **act fails with permissions**: Make sure Docker is running and you have permissions:
138+
```bash
139+
sudo usermod -aG docker $USER
140+
# Log out and back in
141+
```
142+
143+
4. **Workflow fails on syntax**: Check bash syntax in workflow scripts, especially:
144+
- Array definitions
145+
- String substitutions
146+
- EOF delimiters
147+
148+
### Debug Tips
149+
150+
1. **Enable act debug mode**:
151+
```bash
152+
act -j hardware-build --artifact-server-path /tmp/artifacts --verbose
153+
```
154+
155+
2. **Check generated files locally**:
156+
```bash
157+
ls -la /tmp/artifacts/*/km217-wifi-hardware-exports/
158+
unzip -l /tmp/artifacts/*/km217-wifi-hardware-exports/*.zip
159+
```
160+
161+
3. **Validate KiCad CLI commands manually**:
162+
```bash
163+
# In KiCad project directory
164+
kicad-cli sch export pdf --help
165+
kicad-cli pcb export gerbers --help
166+
```
167+
168+
## 📚 References
169+
170+
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
171+
- [act - Local GitHub Actions](https://github.com/nektos/act)
172+
- [KiCad CLI Documentation](https://docs.kicad.org/master/en/cli/cli.html)
173+
- [KiCad Docker Image](https://github.com/the78mole/kicaddev-docker)

‎.github/kicad-projects.yml

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# KiCad Projects Configuration
2+
# This file defines all KiCad projects in the repository for automated workflows
3+
4+
projects:
5+
- name: "KM217-WiFi"
6+
path: "KM217-WiFi"
7+
description: "Main KM217-WiFi Board"
8+
type: "main"
9+
enabled: true
10+
11+
- name: "ETH_W5500"
12+
path: "EXTENSIONS/ETH_W5500"
13+
description: "Ethernet Extension Board"
14+
type: "extension"
15+
enabled: true
16+
17+
# Configuration for workflow behavior
18+
config:
19+
# Default export settings
20+
export:
21+
gerber: true
22+
pdf: true
23+
images: true
24+
3d_models: true
25+
bom: false # Bill of Materials export (if needed later)
26+
27+
# Validation settings
28+
validation:
29+
check_drc: true
30+
check_erc: true
31+
validate_exports: true
32+
33+
# Release settings
34+
release:
35+
create_packages: true
36+
generate_summary: true
37+
upload_artifacts: true
38+
39+
# Global text variables (applied to all projects if not overridden)
40+
text_variables:
41+
COMPANY: "the78mole"
42+
AUTHOR: "Daniel Glaser"
43+
CREATION_DATE: "2025-07-28"

‎.github/workflows/WORKFLOW_UPDATES.md

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Workflow-Anpassungen für Option-Flags
2+
3+
## 🎯 Übersicht der Änderungen
4+
5+
Die Workflow-Dateien wurden erfolgreich aktualisiert, um die neuen Option-Flags für alle konvertierten Skripte zu verwenden.
6+
7+
## ✅ Aktualisierte Workflows
8+
9+
### 1. PR Check Workflow (`pr-check.yml`)
10+
11+
**Konvertierte Skript-Aufrufe:**
12+
- `update-kicad-revision.sh` - Mit `--name`, `--path`, `--description`, `--version`, `--pr`
13+
- `check-kicad-files-with-revision.sh` - Mit `--name`, `--path`, `--description`
14+
- `export-schematics.sh` - Mit `--name`, `--path`, `--description`
15+
- `export-gerber.sh` - Mit `--name`, `--path`, `--description`
16+
- `export-3d-models.sh` - Mit `--name`, `--path`, `--description`
17+
- `validate-export-files.sh` - Mit `--name`, `--path`, `--description`
18+
19+
### 2. Release Workflow (`release.yml`)
20+
21+
**Konvertierte Skript-Aufrufe:**
22+
- `check-kicad-files.sh` - Mit `--name`, `--path`, `--description`
23+
- `export-schematics.sh` - Mit `--name`, `--path`, `--description`
24+
- `export-gerber.sh` - Mit `--name`, `--path`, `--description`
25+
- `export-3d-models.sh` - Mit `--name`, `--path`, `--description`
26+
- `validate-export-files.sh` - Mit `--name`, `--path`, `--description`
27+
28+
## 📋 Vorher/Nachher Vergleich
29+
30+
### Vorher (Positionale Parameter):
31+
```yaml
32+
- name: 🔧 Export Gerber Files
33+
run: |
34+
./.github/workflows/scripts/export-gerber.sh \
35+
"${{ matrix.project.name }}" \
36+
"${{ matrix.project.path }}" \
37+
"${{ matrix.project.description }}"
38+
```
39+
40+
### Nachher (Option-Flags):
41+
```yaml
42+
- name: 🔧 Export Gerber Files
43+
run: |
44+
./.github/workflows/scripts/export-gerber.sh \
45+
--name "${{ matrix.project.name }}" \
46+
--path "${{ matrix.project.path }}" \
47+
--description "${{ matrix.project.description }}"
48+
```
49+
50+
## 🎉 Vorteile der Änderungen
51+
52+
1. **📖 Selbstdokumentation**: Die Workflow-YAML-Dateien sind jetzt selbsterklärend
53+
2. **🔧 Wartbarkeit**: Parameter können einfach hinzugefügt werden ohne Reihenfolge-Abhängigkeit
54+
3. **🐛 Debugging**: Klare Parameter-Identifikation in Workflow-Logs
55+
4. **🔄 Kompatibilität**: Rückwärtskompatibilität durch Fallback auf Positional-Parameter
56+
5. **⚡ Zukunftssicher**: Einfache Erweiterung ohne Breaking Changes
57+
58+
## 🧪 Testempfehlung
59+
60+
Die Workflows können mit dem `act` Tool getestet werden:
61+
62+
```bash
63+
# PR Workflow testen
64+
act pull_request --artifact-server-path /tmp/artifacts
65+
66+
# Release Workflow testen
67+
act push --artifact-server-path /tmp/artifacts
68+
```
69+
70+
## 📊 Status
71+
72+
- **Konvertierte Skripte**: 7/25 ✅
73+
- **Aktualisierte Workflows**: 2/2 ✅
74+
- **Backward Compatibility**: 100% ✅
75+
- **Getestet mit act**: Bereit für Test ⏳
76+
77+
---
78+
*Alle Workflow-Änderungen sind backward-kompatibel und beeinträchtigen nicht die Funktionalität bestehender Setups*

0 commit comments

Comments
 (0)