Skip to content

Commit fbe9d00

Browse files
lyuboxalyuboxa
authored
Merge branch 'main' into lk/exec-activity-via-name
2 parents 5f12304 + 604bff3 commit fbe9d00

37 files changed

+2473
-270
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# go-workflows Development Instructions
2+
3+
Durable workflows library for Go that borrows heavily from Temporal and DTFx. Supports multiple backends (MySQL, Redis, SQLite, in-memory) and provides comprehensive workflow orchestration capabilities.
4+
5+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
6+
7+
## Working Effectively
8+
9+
### Bootstrap and Build
10+
Run these commands in sequence to set up a working development environment:
11+
12+
```bash
13+
# 1. Download Go dependencies - NEVER CANCEL: Takes ~3.5 minutes. Set timeout to 300+ seconds.
14+
go mod download
15+
16+
# 2. Build all packages - Takes ~40 seconds. Set timeout to 120+ seconds.
17+
go build -v ./...
18+
19+
# 3. Start development dependencies - Takes ~13 seconds. Set timeout to 60+ seconds.
20+
docker compose up -d
21+
```
22+
23+
### Testing
24+
```bash
25+
# Run short tests - NEVER CANCEL: Takes ~45 seconds. Set timeout to 120+ seconds.
26+
go test -short -timeout 120s -race -count 1 -v ./...
27+
28+
# Run full test suite - NEVER CANCEL: Takes ~2.5 minutes. Set timeout to 300+ seconds.
29+
go test -timeout 180s -race -count 1 -v ./...
30+
31+
# Install test reporting tool
32+
go install github.com/jstemmer/go-junit-report/v2@latest
33+
34+
# Run tests with JUnit output (as used in CI) - NEVER CANCEL: Takes ~2.5 minutes. Set timeout to 300+ seconds.
35+
go test -timeout 120s -race -count 1 -v ./... 2>&1 | go-junit-report -set-exit-code -iocopy -out "report.xml"
36+
```
37+
38+
### Linting
39+
```bash
40+
# Install golangci-lint
41+
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
42+
43+
# Build custom analyzer plugin - Takes ~8 seconds. Set timeout to 60+ seconds.
44+
go build -tags analyzerplugin -buildmode=plugin analyzer/plugin/plugin.go
45+
46+
# Run basic linting (custom analyzer has version conflicts) - Takes ~12 seconds. Set timeout to 120+ seconds.
47+
~/go/bin/golangci-lint run --disable-all --enable=gofmt,govet,ineffassign,misspell --timeout=5m
48+
```
49+
50+
### Run Sample Applications
51+
```bash
52+
# Simple workflow example with Redis backend (default)
53+
cd samples/simple && go run .
54+
55+
# Simple workflow with SQLite backend
56+
cd samples/simple && go run . -backend sqlite
57+
58+
# Benchmark utility
59+
cd bench && go run .
60+
61+
# Web example with diagnostic UI
62+
cd samples/web && go run .
63+
# Access UI at http://localhost:3000/diag
64+
```
65+
66+
## Validation
67+
68+
### Core Workflow Functionality
69+
Always test core workflow functionality after making changes:
70+
71+
1. **Simple End-to-End Test:**
72+
```bash
73+
cd samples/simple && go run . -backend sqlite
74+
```
75+
Expected output: "Workflow finished. Result: 59"
76+
77+
2. **Multi-Backend Test:**
78+
```bash
79+
# Test Redis backend (requires docker compose up)
80+
cd samples/simple && go run .
81+
82+
# Test SQLite backend (embedded)
83+
cd samples/simple && go run . -backend sqlite
84+
```
85+
86+
3. **Benchmark Validation:**
87+
```bash
88+
cd bench && go run .
89+
```
90+
Expected: Workflow hierarchy execution with metrics output
91+
92+
### Build Validation
93+
Always run these validation steps before committing:
94+
95+
1. **Full Build:** `go build -v ./...` - Must complete without errors
96+
2. **Short Tests:** `go test -short -timeout 120s -race -count 1 -v ./...` - Should pass (1 known non-critical test failure in tester package)
97+
3. **Sample Execution:** At least one sample must run successfully
98+
4. **Basic Linting:** Check for obvious issues with basic linters
99+
100+
### Manual Testing Scenarios
101+
Execute these scenarios to verify workflow functionality:
102+
103+
1. **Basic Activity Workflow:**
104+
- Run `samples/simple`
105+
- Verify workflow executes activities and returns result
106+
- Check no errors in output
107+
108+
2. **Subworkflow Execution:**
109+
- Run `bench` utility
110+
- Verify hierarchical workflow creation and execution
111+
- Check metrics output shows expected activity and workflow counts
112+
113+
3. **Backend Switching:**
114+
- Test same workflow with different backends (Redis, SQLite)
115+
- Verify consistent behavior across backends
116+
117+
## Repository Structure
118+
119+
### Key Directories
120+
- **`/samples/`** - Example applications demonstrating workflow patterns:
121+
- `simple/` - Basic workflow with activities
122+
- `web/` - Web UI example with diagnostics
123+
- `subworkflow/` - Nested workflow patterns
124+
- `timer/` - Timer and scheduling examples
125+
- `signal/` - Signal handling patterns
126+
- **`/backend/`** - Storage backend implementations:
127+
- `mysql/` - MySQL backend
128+
- `redis/` - Redis backend
129+
- `sqlite/` - SQLite backend
130+
- `monoprocess/` - In-memory backend
131+
- **`/workflow/`** - Core workflow execution engine
132+
- **`/activity/`** - Activity execution framework
133+
- **`/tester/`** - Testing utilities for workflow development
134+
- **`/client/`** - Client library for workflow interactions
135+
- **`/worker/`** - Worker process implementation
136+
- **`/analyzer/`** - Custom Go analyzer for workflow code validation
137+
138+
### Build and Configuration Files
139+
- **`go.mod`** - Go module definition with all dependencies
140+
- **`docker-compose.yml`** - Development dependencies (MySQL, Redis)
141+
- **`.golangci.yml`** - Linting configuration (includes custom analyzer)
142+
- **`tools.go`** - Development tool dependencies
143+
- **`.github/workflows/go.yml`** - CI pipeline definition
144+
145+
### Development Dependencies
146+
The project requires Docker services for full functionality:
147+
148+
```bash
149+
# Start MySQL and Redis services
150+
docker compose up -d
151+
152+
# Check service status
153+
docker compose ps
154+
155+
# View logs
156+
docker compose logs
157+
158+
# Stop services
159+
docker compose down
160+
```
161+
162+
## Common Tasks
163+
164+
### Adding New Workflow Examples
165+
1. Create directory under `samples/`
166+
2. Implement workflow and activity functions
167+
3. Add backend selection similar to existing samples
168+
4. Test with multiple backends
169+
5. Add to documentation
170+
171+
### Backend Development
172+
1. Implement `backend.Backend` interface
173+
2. Add database schema/migrations as needed
174+
3. Create integration tests using `backend/test` package
175+
4. Add CI job in `.github/workflows/go.yml`
176+
177+
### Custom Analyzer Rules
178+
1. Modify `analyzer/analyzer.go`
179+
2. Rebuild plugin: `go build -tags analyzerplugin -buildmode=plugin analyzer/plugin/plugin.go`
180+
3. Test with golangci-lint (note: version compatibility issues exist)
181+
182+
## Timing Expectations
183+
184+
| Operation | Time | Timeout Recommendation |
185+
|-----------|------|----------------------|
186+
| `go mod download` | ~3.5 minutes | 300+ seconds |
187+
| `go build -v ./...` | ~40 seconds | 120+ seconds |
188+
| `go test -short` | ~45 seconds | 120+ seconds |
189+
| `go test` (full) | ~2.5 minutes | 300+ seconds |
190+
| `docker compose up -d` | ~13 seconds | 60+ seconds |
191+
| Plugin build | ~8 seconds | 60+ seconds |
192+
| Linting | ~12 seconds | 120+ seconds |
193+
194+
**CRITICAL:** NEVER CANCEL build or test operations. Always wait for completion and use recommended timeout values.
195+
196+
## Known Issues
197+
- Custom analyzer plugin has version conflicts with current golangci-lint
198+
- One test failure in `tester/tester_timers_test.go` (non-critical)
199+
- Various linter warnings present but not blocking
200+
201+
## CI Pipeline
202+
The GitHub Actions workflow (`.github/workflows/go.yml`) runs:
203+
1. Build validation
204+
2. Short tests on main branch
205+
3. Backend-specific tests (Redis, MySQL, SQLite) in parallel
206+
4. Test reporting with summaries
207+
208+
Always ensure your changes pass the same tests that CI runs.

0 commit comments

Comments
 (0)