Skip to content

Commit 470e478

Browse files
Copilotcpuguy83
Copilot
and
cpuguy83
committed
Create comprehensive .github/copilot-instructions.md with validated commands
Co-authored-by: cpuguy83 <799078+cpuguy83@users.noreply.github.com>
1 parent ca5b413 commit 470e478

File tree

2 files changed

+168
-0
lines changed

2 files changed

+168
-0
lines changed

‎--help‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
// Code generated by cmd/gen-source-variants. DO NOT EDIT.
2+
3+
package dalec
4+
5+
import (
6+
"fmt"
7+
)
8+
9+
// validateSourceVariants ensures exactly one source variant is set
10+
func (s *Source) validateSourceVariants() error {
11+
count := 0
12+
13+
if s.Build != nil {
14+
count++
15+
}
16+
if s.Context != nil {
17+
count++
18+
}
19+
if s.DockerImage != nil {
20+
count++
21+
}
22+
if s.Git != nil {
23+
count++
24+
}
25+
if s.HTTP != nil {
26+
count++
27+
}
28+
if s.Inline != nil {
29+
count++
30+
}
31+
32+
switch count {
33+
case 0:
34+
return fmt.Errorf("no non-nil source variant")
35+
case 1:
36+
return nil
37+
default:
38+
return fmt.Errorf("more than one source variant defined")
39+
}
40+
}
41+
42+
// toInterface returns the underlying source interface implementation
43+
func (s *Source) toInterface() source {
44+
switch {
45+
case s.Build != nil:
46+
return s.Build
47+
case s.Context != nil:
48+
return s.Context
49+
case s.DockerImage != nil:
50+
return s.DockerImage
51+
case s.Git != nil:
52+
return s.Git
53+
case s.HTTP != nil:
54+
return s.HTTP
55+
case s.Inline != nil:
56+
return s.Inline
57+
default:
58+
panic(errNoSourceVariant)
59+
}
60+
}

‎.github/copilot-instructions.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Dalec - Package and Container Builder
2+
3+
Dalec is a Docker BuildKit frontend for building system packages (RPM, DEB) and containers from declarative YAML specifications. It supports multiple Linux distributions and Windows containers.
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 Basic Development
10+
- Download Go dependencies: `go mod download` -- takes ~5 seconds
11+
- Run unit tests: `go test --test.short --timeout=10m ./...` -- takes ~52 seconds. NEVER CANCEL. Set timeout to 15+ minutes.
12+
- Generate source files: `go generate` -- takes ~1 second
13+
- Run custom linters: `go run ./cmd/lint ./...` -- takes ~3 seconds
14+
- Validate generated files are up to date: `git diff --exit-code` after running `go generate`
15+
16+
### Building CLI Tools
17+
- Build frontend binary: `go build -o /tmp/frontend ./cmd/frontend` -- takes ~1 second
18+
- Build dalec-redirectio: `go build -o /tmp/dalec-redirectio ./cmd/dalec-redirectio` -- takes ~1 second
19+
- Generate JSON schema: `go run ./cmd/gen-jsonschema` -- takes ~0.2 seconds
20+
- All other CLI tools in `cmd/` can be built with `go build` or run with `go run`
21+
22+
### Docker Frontend Build System
23+
**IMPORTANT**: Docker builds may fail in some environments due to TLS certificate issues with proxy.golang.org. This is an environmental limitation, not a code issue.
24+
25+
- Build frontend image: `docker buildx bake frontend` -- takes ~2-5 minutes when working. NEVER CANCEL. Set timeout to 15+ minutes.
26+
- **Alternative when Docker builds fail**: Use host-compiled binaries for development and testing
27+
- The frontend requires Docker BuildKit with buildx support
28+
29+
### Integration Testing
30+
- Run specific distro tests: `go test -timeout=59m -v ./test -run=TestMariner2` -- takes 30+ minutes. NEVER CANCEL. Set timeout to 75+ minutes.
31+
- Run all integration tests: `go test -timeout=59m -v ./test` -- takes 45+ minutes. NEVER CANCEL. Set timeout to 75+ minutes.
32+
- Tests require Docker and BuildKit to be working properly
33+
- Tests cover multiple Linux distributions: Mariner2, Azlinux3, Jammy, Noble, Bullseye, Bookworm, etc.
34+
35+
## Validation
36+
37+
### Always Run Before Committing
38+
- `go test --test.short ./...` -- validates unit tests pass
39+
- `go run ./cmd/lint ./...` -- validates custom linting rules
40+
- `go generate && git diff --exit-code` -- validates generated files are up to date
41+
- Consider running integration tests for your target distribution if making significant changes
42+
43+
### Manual Validation Scenarios
44+
- **CLI Tool Testing**: Build and run `go build -o /tmp/frontend ./cmd/frontend` then test with `--help` flag
45+
- **Schema Generation**: Run `go run ./cmd/gen-jsonschema` and verify JSON schema output is valid
46+
- **Example Spec Validation**: Use `docs/examples/go-md2man.yml` as a test case for spec validation
47+
48+
### Docker Build Validation (When Working)
49+
- Build example: `docker build -t go-md2man:test -f docs/examples/go-md2man.yml --target=azlinux3/rpm --output=_output .`
50+
- Container example: `docker build -t go-md2man:test -f docs/examples/go-md2man.yml --target=azlinux3 .`
51+
52+
## Common Tasks
53+
54+
### Repo Structure
55+
```
56+
.
57+
├── cmd/ # CLI tools and binaries
58+
│ ├── frontend/ # Main BuildKit frontend
59+
│ ├── gen-jsonschema/ # JSON schema generator
60+
│ ├── lint/ # Custom linters
61+
│ └── ... # Other tools
62+
├── docs/examples/ # Example Dalec specs
63+
├── test/ # Integration tests
64+
├── targets/ # Target-specific implementations
65+
├── website/ # Documentation (Docusaurus)
66+
├── docker-bake.hcl # Docker Buildx configuration
67+
├── Dockerfile # Frontend container definition
68+
└── go.mod # Go module definition
69+
```
70+
71+
### Key Files to Monitor
72+
- Always regenerate files after modifying source variants: `go generate`
73+
- Always run linting after changes: `go run ./cmd/lint ./...`
74+
- Check `docker-bake.hcl` for Docker build targets and configurations
75+
- Check `docs/examples/go-md2man.yml` for canonical example of Dalec spec format
76+
77+
### Important Directories
78+
- `cmd/` - All CLI tools and main binaries
79+
- `test/` - Comprehensive integration test suite
80+
- `targets/` - Platform-specific build logic (Linux RPM/DEB, Windows)
81+
- `frontend/` - Core BuildKit frontend implementation
82+
- `website/docs/` - User documentation and examples
83+
84+
## Development Environment Requirements
85+
86+
### Required Tools
87+
- Go 1.23+ (check with `go version`)
88+
- Docker with BuildKit support (check with `docker buildx version`)
89+
- Standard Unix tools (git, make, etc.)
90+
91+
### Optional but Recommended
92+
- Node.js 18+ for documentation site (`cd website && npm start`)
93+
- golangci-lint for additional linting (though custom linter is primary)
94+
95+
### Environment Limitations
96+
- Docker builds may fail due to network/certificate issues in some environments
97+
- Integration tests require full Docker functionality
98+
- Host-based Go builds always work and are sufficient for most development
99+
100+
### Time Expectations
101+
- Unit tests: ~1 minute
102+
- Custom linting: ~3 seconds
103+
- Code generation: ~1 second
104+
- Frontend binary build: ~1 second
105+
- Docker frontend build: 2-5 minutes (when working)
106+
- Integration test suite: 45+ minutes for full suite, 30+ minutes for single distro
107+
108+
Remember: NEVER CANCEL long-running commands. Build and test operations can legitimately take 30-60+ minutes.

0 commit comments

Comments
 (0)