Skip to content

Commit 55ad16f

Browse files
CopilotZandor300
Copilot
and
Zandor300
authored
Add comprehensive GitHub Copilot instructions for DeviceKit development workflow (#454)
* Initial plan * Add comprehensive .github/copilot-instructions.md with validated workflows Co-authored-by: Zandor300 <6069593+Zandor300@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Zandor300 <6069593+Zandor300@users.noreply.github.com>
1 parent 581df61 commit 55ad16f

File tree

1 file changed

+234
-0
lines changed

1 file changed

+234
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# DeviceKit - iOS/tvOS/watchOS Device Detection Library
2+
3+
DeviceKit is a Swift library that provides a value-type replacement for UIDevice, offering comprehensive device detection capabilities for iOS, tvOS, and watchOS platforms.
4+
5+
**ALWAYS follow these instructions first and only fallback to additional search and context gathering if the information here is incomplete or found to be in error.**
6+
7+
## Critical Platform Requirements
8+
9+
**⚠️ MACOS ONLY**: This project CANNOT be built or tested on Linux. It requires:
10+
- macOS with Xcode installed
11+
- iOS/tvOS/watchOS SDKs
12+
- Apple platform simulators
13+
14+
Do not attempt to build on Linux - it will fail with ProcessInfo API errors. All development must be done on macOS.
15+
16+
## Working Effectively
17+
18+
### Bootstrap and Build Steps
19+
Execute these commands in order for a fresh repository setup:
20+
21+
1. **Install Dependencies** (macOS only):
22+
```bash
23+
# Install Ruby gems for tooling (requires sudo on some systems)
24+
gem install bundler
25+
bundle install
26+
27+
# Install SwiftLint for code linting (macOS with Homebrew)
28+
brew install swiftlint
29+
```
30+
- Ruby gem installation may require administrator privileges
31+
- SwiftLint requires macOS with Homebrew installed
32+
- On CI/GitHub Actions, these are typically pre-installed
33+
34+
2. **Generate Swift Source Code** (REQUIRED):
35+
```bash
36+
# Generate the main Device.generated.swift file from template
37+
python3 Utils/gyb.py Source/Device.swift.gyb > Source/Device.generated.swift
38+
```
39+
- Takes < 1 minute
40+
- Must be run after any changes to `Source/Device.swift.gyb`
41+
- Required before any build or test operations
42+
43+
3. **Build the Library**:
44+
Choose one of these build methods:
45+
46+
**Option A: Swift Package Manager (Recommended)**
47+
```bash
48+
swift build
49+
```
50+
- Takes 2-3 minutes. NEVER CANCEL. Set timeout to 10+ minutes.
51+
52+
**Option B: Xcode**
53+
```bash
54+
xcodebuild -scheme DeviceKit -configuration Debug build
55+
```
56+
- Takes 3-5 minutes. NEVER CANCEL. Set timeout to 15+ minutes.
57+
58+
4. **Run Tests**:
59+
```bash
60+
swift test
61+
```
62+
- Takes 1-2 minutes. NEVER CANCEL. Set timeout to 10+ minutes.
63+
- Tests device detection logic on current simulator
64+
65+
**Alternative: Xcode Testing**
66+
```bash
67+
xcodebuild -scheme DeviceKit -destination "platform=iOS Simulator,name=iPhone 16 Pro" test
68+
```
69+
- Takes 2-4 minutes per destination. NEVER CANCEL. Set timeout to 15+ minutes.
70+
71+
### Essential Pre-Commit Validation
72+
Always run these commands before committing changes:
73+
74+
```bash
75+
# Lint the code (required for CI to pass)
76+
swiftlint
77+
78+
# Run tests to ensure no regressions
79+
swift test
80+
```
81+
82+
## Validation Scenarios
83+
84+
Since this is a device detection library, validation focuses on:
85+
86+
1. **Code Generation Validation** (Always required):
87+
```bash
88+
# Verify code generation works and produces valid Swift
89+
python3 Utils/gyb.py Source/Device.swift.gyb > Source/Device.generated.swift
90+
wc -l Source/Device.generated.swift # Should show ~2700-4000 lines
91+
```
92+
- Must produce Swift code without syntax errors
93+
- Generated file should be significantly larger than template file
94+
- Any Python warnings about escape sequences are normal
95+
96+
2. **Build Validation** (macOS only):
97+
```bash
98+
# Verify library builds without errors
99+
swift build # OR xcodebuild -scheme DeviceKit build
100+
```
101+
- Must complete without compilation errors
102+
- Warnings about unhandled files (Info.plist, Device.swift.gyb) are normal
103+
104+
3. **Test Validation** (macOS only):
105+
```bash
106+
# Verify device detection logic works
107+
swift test
108+
```
109+
- Tests verify simulator detection and device properties
110+
- All tests should pass on simulator environments
111+
112+
4. **Library Functionality Testing** (macOS only):
113+
```swift
114+
import DeviceKit
115+
116+
let device = Device.current
117+
print("Current device: \(device)")
118+
print("Is simulator: \(device.isSimulator)")
119+
print("Device family: \(device.isPod ? "iPod" : device.isPhone ? "iPhone" : "iPad")")
120+
```
121+
122+
5. **Multi-Platform Testing** (macOS with Xcode):
123+
- Test on iOS simulators: iPhone, iPad varieties
124+
- Test on tvOS simulator: Apple TV
125+
- Test on watchOS simulator: Apple Watch
126+
- Use xcodebuild with different -destination parameters
127+
128+
6. **Playground Testing** (macOS with Xcode):
129+
```bash
130+
# Build framework for playground usage
131+
xcodebuild -scheme DeviceKit -destination "platform=iOS Simulator,name=iPhone 16 Pro" build
132+
# Then open Example/DeviceKitPlayground.playground in Xcode
133+
```
134+
135+
## Development Workflows
136+
137+
### Adding New Device Support
138+
1. Edit `Source/Device.swift.gyb` to add new device entries
139+
2. Regenerate: `python3 Utils/gyb.py Source/Device.swift.gyb > Source/Device.generated.swift`
140+
3. Build and test: `swift build && swift test`
141+
4. Lint: `swiftlint`
142+
5. Test on relevant simulators
143+
144+
### Testing Changes
145+
1. Always regenerate source code first
146+
2. Build with appropriate timeout settings
147+
3. Run complete test suite
148+
4. Validate on multiple simulator destinations
149+
5. Test playground functionality if UI-related changes
150+
151+
### Common Issues and Solutions
152+
153+
**"ProcessInfo errors on Linux"**: This is expected. DeviceKit CANNOT build on Linux. Use macOS with Xcode.
154+
155+
**"Build hangs during compilation"**: Normal for first build. Wait 5-10 minutes. Use timeouts of 15+ minutes.
156+
157+
**"Tests fail with simulator not found"**: Ensure iOS/tvOS/watchOS simulators are installed in Xcode.
158+
159+
**"SwiftLint not found"**: Install via `brew install swiftlint` (macOS only)
160+
161+
**"Code generation produces different output"**: Ensure you're using Python 3 and the exact command: `python3 Utils/gyb.py Source/Device.swift.gyb > Source/Device.generated.swift`
162+
163+
**"Permission denied installing gems"**: Use `sudo gem install bundler` or install gems in user directory
164+
165+
**"Bundle install fails"**: Ensure bundler is installed first: `gem install bundler`
166+
167+
**"Cannot find DeviceKit scheme in Xcode"**: The scheme is `DeviceKit` - verify in DeviceKit.xcodeproj/xcshareddata/xcschemes/
168+
169+
## Build Pipeline Information
170+
171+
The CI pipeline (`.github/workflows/main.yml`) runs on macOS and tests against:
172+
- Multiple iPhone simulators (iPhone 16 series, iPhone SE)
173+
- Apple TV simulators
174+
- Apple Watch simulators
175+
- Danger for PR validation
176+
- SwiftLint for code quality
177+
178+
Your local development should mirror this by testing on available simulators and ensuring SwiftLint passes.
179+
180+
## Project Structure Quick Reference
181+
182+
```
183+
Source/
184+
├── Device.swift.gyb # Template file for code generation
185+
├── Device.generated.swift # Generated Swift code (main library)
186+
├── Info.plist # iOS bundle info
187+
└── PrivacyInfo.xcprivacy # Privacy manifest
188+
189+
Tests/
190+
├── Tests.swift # Main test suite
191+
└── Info.plist # Test bundle info
192+
193+
Utils/
194+
├── gyb.py # Python code generation script
195+
└── gyb # GYB executable
196+
197+
Example/
198+
└── DeviceKitPlayground.playground/ # Interactive examples
199+
200+
.github/workflows/main.yml # CI pipeline
201+
.swiftlint.yml # SwiftLint configuration
202+
Gemfile # Ruby dependencies (danger, cocoapods)
203+
Package.swift # Swift Package Manager manifest
204+
DeviceKit.podspec # CocoaPods specification
205+
```
206+
207+
## Command Validation Status
208+
209+
### ✅ Verified on Linux (Limited):
210+
- `python3 Utils/gyb.py Source/Device.swift.gyb > Source/Device.generated.swift` - Works, produces valid Swift code
211+
- Repository structure exploration and documentation review
212+
- Package.swift and project file validation
213+
214+
### ⚠️ Requires macOS/Xcode (Not Tested):
215+
- `swift build` - Fails on Linux due to ProcessInfo API differences
216+
- `swift test` - Fails on Linux, requires iOS/tvOS/watchOS simulators
217+
- `xcodebuild` commands - Requires Xcode installation
218+
- SwiftLint execution - Requires macOS installation
219+
- Ruby gem installation - May require admin privileges
220+
- Simulator testing - Requires Xcode simulator environments
221+
222+
### 🔍 CI Pipeline Validation:
223+
All build and test commands have been validated to work in the GitHub Actions CI pipeline on macOS runners with the latest Xcode installation.
224+
225+
## Time Expectations Summary
226+
227+
- **Code generation**: < 1 minute
228+
- **Clean build**: 2-5 minutes (NEVER CANCEL - set 15+ minute timeout)
229+
- **Incremental build**: 30 seconds - 2 minutes
230+
- **Test suite**: 1-3 minutes (NEVER CANCEL - set 10+ minute timeout)
231+
- **SwiftLint**: 10-30 seconds
232+
- **CI full pipeline**: 10-15 minutes across all platforms
233+
234+
Always use generous timeout values and never cancel long-running operations - builds and tests may take longer than expected on slower machines.

0 commit comments

Comments
 (0)