Skip to content

Commit 9aa047b

Browse files
Copilotyxxhero
Copilot
and
yxxhero
authored
Add comprehensive GitHub Copilot instructions for Dragonfly development (#4281)
* Initial plan * Create comprehensive copilot instructions with validated commands and timing Co-authored-by: yxxhero <11087727+yxxhero@users.noreply.github.com> * Remove build artifacts from git and update .gitignore Co-authored-by: yxxhero <11087727+yxxhero@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: yxxhero <11087727+yxxhero@users.noreply.github.com>
1 parent 18695a8 commit 9aa047b

File tree

2 files changed

+180
-0
lines changed

2 files changed

+180
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Dragonfly P2P File Distribution System
2+
3+
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.
4+
5+
Dragonfly is a P2P file distribution and image acceleration system written in Go 1.23.8. It consists of multiple components: manager (cluster management and web portal), scheduler (download optimization), dfget (P2P download client), dfcache (P2P cache operations), and dfstore (object storage with P2P cache).
6+
7+
## Working Effectively
8+
9+
### Bootstrap and Build Process
10+
Install required dependencies and build the project:
11+
12+
```bash
13+
# Install Go tools (required for linting and testing)
14+
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin
15+
go install github.com/onsi/ginkgo/v2/ginkgo@latest
16+
export PATH=$PATH:$(go env GOPATH)/bin
17+
18+
# Build all components (takes ~1.5 minutes)
19+
make build-manager-server build-scheduler build-dfget build-dfcache build-dfstore
20+
# NEVER CANCEL: Build takes 2 minutes. Set timeout to 5+ minutes.
21+
22+
# Verify build success
23+
ls -la bin/linux_amd64/
24+
./bin/linux_amd64/dfget version
25+
./bin/linux_amd64/scheduler version
26+
./bin/linux_amd64/manager version
27+
```
28+
29+
**CRITICAL**: The full `make build` target will fail because `build-manager-console` requires a Node.js frontend that is not included in this repository. Always use the individual build targets listed above to build only the Go components.
30+
31+
### Testing
32+
Run different test suites with appropriate timeouts:
33+
34+
```bash
35+
# Format and vet code (takes ~20 seconds)
36+
make fmt vet
37+
# NEVER CANCEL: Set timeout to 2+ minutes.
38+
39+
# Run linting (takes ~1.5 minutes)
40+
make markdownlint # Takes ~5 seconds
41+
golangci-lint run --timeout=10m # Takes ~1.5 minutes
42+
# NEVER CANCEL: Linting takes 2 minutes total. Set timeout to 5+ minutes.
43+
44+
# Run unit tests (takes ~3.5 minutes, may have some failures in fresh environment)
45+
make test
46+
# NEVER CANCEL: Unit tests take 4 minutes. Set timeout to 10+ minutes.
47+
# Note: Some tests may fail in sandboxed environments, this is expected.
48+
49+
# Run E2E tests (requires Docker and longer setup)
50+
make e2e-test
51+
# NEVER CANCEL: E2E tests take 10+ minutes. Set timeout to 30+ minutes.
52+
```
53+
54+
### Running Applications
55+
Test the built applications:
56+
57+
```bash
58+
# Test CLI help (validates binaries work correctly)
59+
./bin/linux_amd64/dfget --help
60+
./bin/linux_amd64/dfcache --help
61+
./bin/linux_amd64/dfstore --help
62+
./bin/linux_amd64/scheduler --help
63+
./bin/linux_amd64/manager --help
64+
65+
# Test version commands (validates build was successful)
66+
./bin/linux_amd64/dfget version
67+
./bin/linux_amd64/scheduler version
68+
./bin/linux_amd64/manager version
69+
```
70+
71+
**Important**: You cannot run the full Dragonfly system in a sandboxed environment without proper network configuration, certificates, and storage backends. The components require complex setup with Redis, databases, and network connectivity between peers.
72+
73+
## Validation Requirements
74+
75+
### Pre-commit Validation
76+
Always run these commands before committing changes:
77+
78+
```bash
79+
# NEVER CANCEL: Full precheck takes 8 minutes. Set timeout to 15+ minutes.
80+
make fmt vet
81+
golangci-lint run --timeout=10m
82+
make build-manager-server build-scheduler build-dfget build-dfcache build-dfstore
83+
84+
# Test that binaries still work
85+
./bin/linux_amd64/dfget version
86+
./bin/linux_amd64/scheduler version
87+
./bin/linux_amd64/manager version
88+
```
89+
90+
### Scenario Testing
91+
After making changes, always validate:
92+
93+
1. **Build Success**: All Go components build without errors
94+
2. **Binary Functionality**: Version commands execute successfully
95+
3. **Help Commands**: All help text displays correctly
96+
4. **Linting**: No linting errors introduced
97+
98+
## Repository Structure
99+
100+
### Key Directories
101+
- `cmd/`: Main entry points for each component (dfget, scheduler, manager, dfcache, dfstore)
102+
- `pkg/`: Shared libraries and utilities
103+
- `scheduler/`: Scheduler service implementation
104+
- `manager/`: Manager service implementation
105+
- `client/`: Client-side P2P logic
106+
- `test/`: Unit and E2E test suites
107+
- `hack/`: Build scripts and utilities
108+
- `api/`: API definitions and generated code
109+
110+
### Build Artifacts
111+
- `bin/linux_amd64/`: Built binaries (created by build process)
112+
- `coverage.txt`: Test coverage reports
113+
114+
### Important Files
115+
- `Makefile`: All build, test, and lint targets
116+
- `go.mod`: Go 1.23.8 dependencies
117+
- `.golangci.yml`: Linting configuration
118+
- `.markdownlint.yml`: Markdown linting rules
119+
120+
## Timing Expectations
121+
122+
| Command | Duration | Timeout Recommendation |
123+
|---------|----------|------------------------|
124+
| `make fmt vet` | 20 seconds | 2 minutes |
125+
| `make markdownlint` | 5 seconds | 1 minute |
126+
| `golangci-lint run` | 1.5 minutes | 5 minutes |
127+
| Build (Go only) | 1.5 minutes | 5 minutes |
128+
| `make test` | 3.5 minutes | 10 minutes |
129+
| `make e2e-test` | 10+ minutes | 30 minutes |
130+
| Full precheck | 8 minutes | 15 minutes |
131+
132+
**CRITICAL**: NEVER CANCEL long-running commands. Builds and tests are CPU-intensive and require time to complete.
133+
134+
## Common Tasks
135+
136+
### Viewing Build Targets
137+
```bash
138+
make help
139+
```
140+
141+
### Clean Build
142+
```bash
143+
make clean
144+
rm -rf bin/
145+
```
146+
147+
### Adding Dependencies
148+
```bash
149+
go mod tidy
150+
go mod download
151+
```
152+
153+
## Troubleshooting
154+
155+
### Build Issues
156+
- **"build-manager-console" fails**: This is expected. The console frontend is not included. Use individual component build targets.
157+
- **Missing tools**: Install golangci-lint and ginkgo as shown in bootstrap section.
158+
- **Go version**: Requires Go 1.23.8 as specified in go.mod.
159+
160+
### Test Issues
161+
- **Unit test failures**: Some tests may fail in sandboxed environments due to network/permission restrictions. This is expected.
162+
- **E2E test failures**: Require Docker and complex setup. May not work in all environments.
163+
164+
### Runtime Issues
165+
- **"command not found"**: Add `$(go env GOPATH)/bin` to PATH for installed Go tools.
166+
- **Binary execution**: Built binaries are in `bin/linux_amd64/` directory.
167+
168+
## Development Workflow
169+
170+
1. **Make changes** to Go source files
171+
2. **Format and vet**: `make fmt vet`
172+
3. **Build**: Individual component build targets
173+
4. **Test**: `./bin/linux_amd64/[component] version` to verify
174+
5. **Lint**: `golangci-lint run --timeout=10m`
175+
6. **Unit test**: `make test` (optional, may fail in sandbox)
176+
7. **Commit** changes
177+
178+
Always build and validate binary functionality after code changes to ensure nothing is broken.

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,3 +65,5 @@ deploy/docker-compose/log
6565
deploy/docker-compose/config
6666
test/e2e/v1/*.log
6767
test/e2e/*.log
68+
# Exclude build artifacts
69+
bin/

0 commit comments

Comments
 (0)