Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 005b7d5

Browse files
CopilotCopilot
authored
Add comprehensive GitHub Copilot instructions with beta branch targeting strategy for Homebridge development (#3838)
1 parent be3852e commit 005b7d5

File tree

1 file changed

+153
-0
lines changed

1 file changed

+153
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Homebridge
2+
3+
Homebridge is a lightweight Node.js server that emulates the iOS HomeKit API, allowing "smart home" devices to integrate with Apple's HomeKit ecosystem through community-contributed plugins.
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+
## Branch Targeting Strategy
8+
9+
When creating pull requests or working with branches, always prioritize targeting in this order:
10+
1. **Target the lowest beta branch first** (e.g., beta-2.0.0)
11+
2. **If no lower beta branch exists, target the next beta branch** (e.g., beta-3.0.0)
12+
3. **Only target the latest branch as a last resort**
13+
14+
This ensures changes are properly tested in beta releases before being merged to the main release branch.
15+
16+
## Working Effectively
17+
18+
- Bootstrap, build, and test the repository:
19+
- `npm install` -- takes ~20 seconds. Install dependencies first.
20+
- `npm run build` -- takes ~3 seconds. Compiles TypeScript to JavaScript in lib/ directory.
21+
- `npm run test` -- takes ~7 seconds. Runs Jest test suite with 64 tests across 8 suites.
22+
- `npm run lint` -- takes ~2 seconds. ALWAYS run before committing or CI will fail.
23+
- Run Homebridge:
24+
- ALWAYS run build steps first
25+
- `./bin/homebridge -D` -- starts in debug mode, requires config.json in ~/.homebridge/
26+
- `./bin/homebridge -D -U /path/to/config` -- uses custom config directory
27+
- `./bin/homebridge --help` -- shows all CLI options
28+
- Development mode:
29+
- `npm run dev` -- runs with DEBUG=* environment and example plugins
30+
- `npm run watch` -- uses nodemon to auto-rebuild and restart on changes
31+
32+
## Validation
33+
34+
- ALWAYS manually validate Homebridge startup after making changes by running `./bin/homebridge -D`
35+
- ALWAYS run `npm run lint` before committing or the CI (.github/workflows/build.yml) will fail
36+
- Run `npm run test-coverage` to generate coverage reports (takes ~10 seconds)
37+
- Verify that Homebridge shows QR code and bridge information when starting successfully
38+
- Test with minimal config to ensure core functionality works
39+
40+
## Plugin Development Workflow
41+
42+
The most common development scenario is creating or testing Homebridge plugins:
43+
44+
- Create plugin in separate directory
45+
- In plugin directory: `npm link` (makes plugin globally available)
46+
- Create test config in `~/.homebridge-dev/config.json` with your plugin configuration
47+
- Start Homebridge: `homebridge -D -U ~/.homebridge-dev` (uses separate config from production)
48+
- Undo plugin link: `npm unlink` when done
49+
50+
## Common Tasks
51+
52+
The following are outputs from frequently run commands. Reference them instead of viewing, searching, or running bash commands to save time.
53+
54+
### Repository structure
55+
```
56+
/home/runner/work/homebridge/homebridge/
57+
├── README.md # Main documentation
58+
├── package.json # npm configuration and scripts
59+
├── tsconfig.json # TypeScript compiler configuration
60+
├── .eslintrc # ESLint configuration
61+
├── jest.config.js # Jest test configuration
62+
├── bin/homebridge # Main executable script
63+
├── config-sample.json # Sample configuration file
64+
├── src/ # TypeScript source code
65+
│ ├── cli.ts # Command line interface entry point
66+
│ ├── server.ts # Main server logic
67+
│ ├── api.ts # Plugin API definitions
68+
│ ├── pluginManager.ts # Plugin loading and management
69+
│ ├── bridgeService.ts # HomeKit bridge functionality
70+
│ ├── logger.ts # Logging system
71+
│ ├── util/ # Utility functions
72+
│ └── types/ # TypeScript type definitions
73+
├── lib/ # Compiled JavaScript (created by build)
74+
└── docs/ # Generated API documentation
75+
```
76+
77+
### Key npm scripts
78+
```json
79+
{
80+
"build": "npm run clean && tsc",
81+
"clean": "npm install rimraf && rimraf lib/",
82+
"test": "jest --forceExit --detectOpenHandles",
83+
"test-coverage": "jest --coverage --forceExit --detectOpenHandles",
84+
"lint": "eslint 'src/**/*.{js,ts,json}'",
85+
"lint:fix": "npm run lint -- --fix",
86+
"docs": "typedoc",
87+
"dev": "DEBUG=* ./bin/homebridge -D -P example-plugins/ || true",
88+
"watch": "nodemon"
89+
}
90+
```
91+
92+
### CLI options (homebridge --help)
93+
```
94+
Options:
95+
-V, --version output the version number
96+
-C, --color force color in logging
97+
-D, --debug turn on debug level logging
98+
-I, --insecure allow unauthenticated requests (for easier hacking)
99+
-P, --plugin-path [path] look for plugins installed at [path]
100+
-Q, --no-qrcode do not issue QRcode in logging
101+
-K, --keep-orphans keep cached accessories for which plugin is not loaded
102+
-T, --no-timestamp do not issue timestamps in logging
103+
-U, --user-storage-path [path] look for homebridge user files at [path]
104+
--strict-plugin-resolution only load plugins from --plugin-path if set
105+
```
106+
107+
### Sample minimal config.json
108+
```json
109+
{
110+
"bridge": {
111+
"name": "Homebridge Test",
112+
"username": "CC:22:3D:E3:CE:31",
113+
"manufacturer": "homebridge.io",
114+
"model": "homebridge",
115+
"port": 51827,
116+
"pin": "031-45-155"
117+
},
118+
"accessories": [],
119+
"platforms": []
120+
}
121+
```
122+
123+
### Node.js requirements
124+
- Supported versions: Node.js ^18.15.0 || ^20.7.0 || ^22
125+
- Current environment: Node.js v20.19.4 (compatible)
126+
127+
## Project Architecture
128+
129+
- **Entry Point**: `bin/homebridge` executable calls `lib/cli.js` (compiled from `src/cli.ts`)
130+
- **Core Server**: `src/server.ts` manages the main Homebridge server and plugin lifecycle
131+
- **Plugin System**: `src/pluginManager.ts` handles loading npm packages with "homebridge-plugin" keyword
132+
- **HomeKit Bridge**: `src/bridgeService.ts` manages HAP (HomeKit Accessory Protocol) communication
133+
- **API Layer**: `src/api.ts` provides the API interface that plugins use
134+
- **Configuration**: JSON-based config system with bridge settings, accessories, and platforms
135+
136+
## Development Tips
137+
138+
- The build is very fast (~3 seconds) so rebuild frequently during development
139+
- All tests run quickly (~7 seconds) so run them often
140+
- Use `npm run watch` for continuous development with auto-restart
141+
- Plugin development is the most common use case - always test with `npm link` workflow
142+
- Use separate config directories (`-U` flag) to avoid disrupting production Homebridge instances
143+
- Check the generated QR code and pairing information to verify successful startup
144+
- The project uses TypeScript with strict settings - pay attention to type definitions
145+
- ESLint is configured with specific rules - use `npm run lint:fix` to auto-fix style issues
146+
147+
## Common Issues to Check
148+
149+
- Missing config.json: Homebridge will start but show "config.json not found"
150+
- Missing plugins: Homebridge will start but show "No plugin was found for..." messages
151+
- Port conflicts: Change the port in bridge configuration if 51826 is in use
152+
- Permission issues: Homebridge may need elevated permissions for low ports (< 1024)
153+
- Plugin compatibility: Ensure plugins are compatible with current Homebridge version (v1.11.0)

0 commit comments

Comments
 (0)