Skip to content

Commit 010806b

Browse files
Copilotnzakas
Copilot
and
nzakas
authored
docs: Add GitHub Copilot instructions (#228)
* Initial plan * Add comprehensive GitHub Copilot instructions with validated commands Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com>
1 parent d4a6a23 commit 010806b

File tree

1 file changed

+182
-0
lines changed

1 file changed

+182
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# ESLint GitHub Bot
2+
3+
ESLint GitHub Bot is a Probot-based GitHub application that automates common tasks for repositories managed by the ESLint team. The bot handles commit message validation, work-in-progress PR management, automatic issue assignment, release monitoring, recurring issue creation, and needs-info processing.
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 Setup
10+
- Clone the repository
11+
- `npm install` -- takes 1-30 seconds depending on npm cache state. Works with Node.js 20.x but shows engine warnings (expects Node.js 22.x)
12+
- Create `.env` file for local development:
13+
```bash
14+
echo 'APP_ID=12345
15+
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
16+
[valid PEM private key content]
17+
-----END RSA PRIVATE KEY-----"
18+
WEBHOOK_SECRET=test_webhook_secret_123
19+
PORT=3000' > .env
20+
```
21+
22+
### Build and Test
23+
- `npm run lint` -- takes ~1.5 seconds. NEVER CANCEL. Uses ESLint with eslint-config-eslint
24+
- `npm test` -- takes ~3 seconds. NEVER CANCEL. Runs Jest with 284 tests achieving 98.31% coverage
25+
- Run the web server: `npm start` -- starts immediately on port 3000
26+
- Health check: `curl http://localhost:3000/ping` returns "PONG" in ~1.6ms
27+
28+
### Environment Requirements
29+
- Node.js 22.x preferred (works on 20.x with warnings)
30+
- npm 10.x
31+
- Environment variables for server operation:
32+
- `APP_ID`: GitHub app ID (can be dummy value like 12345 for local testing)
33+
- `PRIVATE_KEY`: Valid PEM private key (required format, can be test key for local development)
34+
- `WEBHOOK_SECRET`: Webhook secret (can be dummy value for local testing)
35+
- `PORT`: Server port (optional, defaults to 3000)
36+
37+
## Validation
38+
39+
### Manual Testing Requirements
40+
- ALWAYS run the full test suite after making changes: `npm test`
41+
- ALWAYS run linting before committing: `npm run lint`
42+
- Test server startup: `npm start` and verify health check responds: `curl http://localhost:3000/ping`
43+
- For plugin changes, run relevant test files: `npm test tests/plugins/[plugin-name]/index.js`
44+
45+
### Critical Timing Requirements
46+
- **NEVER CANCEL** any commands - all operations complete quickly
47+
- npm install: 1-30 seconds (set timeout to 60+ seconds)
48+
- npm test: ~3 seconds (set timeout to 30+ seconds)
49+
- npm run lint: ~1.5 seconds (set timeout to 30+ seconds)
50+
- Server startup: immediate (set timeout to 10+ seconds)
51+
52+
## Common Tasks
53+
54+
### Plugin Development
55+
The bot uses a plugin architecture with 6 core plugins in `src/plugins/`:
56+
57+
1. **auto-assign** (`src/plugins/auto-assign/index.js`): Auto-assigns issues to users who indicate willingness to submit PRs
58+
2. **commit-message** (`src/plugins/commit-message/index.js`): Validates PR titles follow ESLint commit message guidelines
59+
3. **needs-info** (`src/plugins/needs-info/index.js`): Adds comments when "needs info" label is added to issues
60+
4. **recurring-issues** (`src/plugins/recurring-issues/index.js`): Creates new scheduled release and TSC meeting issues
61+
5. **release-monitor** (`src/plugins/release-monitor/index.js`): Manages PR status during release phases
62+
6. **wip** (`src/plugins/wip/index.js`): Handles work-in-progress PR status based on title/labels
63+
64+
### Adding New Plugins
65+
1. Create plugin file in `src/plugins/[plugin-name]/index.js`
66+
2. Add plugin to exports in `src/plugins/index.js`
67+
3. Add plugin to enabled list in `src/app.js`
68+
4. Create tests in `tests/plugins/[plugin-name]/index.js`
69+
5. Follow existing plugin patterns using Probot event handlers
70+
71+
### File Structure Reference
72+
```
73+
src/
74+
├── app.js # Main application entry point
75+
├── constants.js # Shared constants (currently empty)
76+
└── plugins/
77+
├── index.js # Plugin exports
78+
├── auto-assign/
79+
├── commit-message/
80+
├── needs-info/
81+
├── recurring-issues/
82+
├── release-monitor/
83+
└── wip/
84+
85+
tests/
86+
├── __mocks__/ # Test mocks
87+
└── plugins/ # Plugin tests mirror src structure
88+
89+
.github/
90+
└── workflows/
91+
├── ci.yml # CI pipeline (lint + test)
92+
├── deploy.yml # Deployment workflow
93+
├── add-to-triage.yml
94+
└── stale.yml
95+
96+
docs/
97+
├── commit-message-check.md # Commit message validation docs
98+
└── edit-pr-title-explanation.png
99+
```
100+
101+
### Key Configuration Files
102+
- `package.json`: Dependencies, scripts, Jest config
103+
- `eslint.config.js`: ESLint configuration using eslint-config-eslint
104+
- `.editorconfig`: Code formatting rules
105+
- `Procfile`: Production deployment config for Dokku
106+
- `.gitignore`: Excludes node_modules, coverage, .env, *.pem files
107+
108+
### Common Command Outputs
109+
110+
#### Repository Root Files
111+
```bash
112+
$ ls -la
113+
.editorconfig
114+
.git/
115+
.github/
116+
.gitignore
117+
.npmrc
118+
CONTRIBUTING.md
119+
LICENSE
120+
Procfile
121+
README.md
122+
docs/
123+
eslint.config.js
124+
package-lock.json
125+
package.json
126+
src/
127+
tests/
128+
```
129+
130+
#### Package.json Scripts
131+
```json
132+
{
133+
"scripts": {
134+
"lint": "eslint .",
135+
"lint:fix": "npm run lint -- --fix",
136+
"start": "node ./src/app.js",
137+
"test": "jest --colors --verbose --coverage"
138+
}
139+
}
140+
```
141+
142+
#### Test Coverage Summary
143+
```
144+
All files | 98.31 | 93.1 | 98.36 | 98.21 |
145+
Test Suites: 6 passed, 6 total
146+
Tests: 284 passed, 284 total
147+
Time: ~3 seconds
148+
```
149+
150+
## Troubleshooting
151+
152+
### Node.js Version Warnings
153+
- Repository expects Node.js 22.x but works on 20.x with warnings
154+
- Engine warnings are normal and do not prevent functionality
155+
- All commands and tests work correctly despite version mismatch
156+
157+
### Server Won't Start
158+
- Ensure `.env` file exists with required environment variables
159+
- `PRIVATE_KEY` must be valid PEM format (can be test key for local development)
160+
- Server defaults to port 3000, check for port conflicts
161+
162+
### Test Failures
163+
- Run `npm install` to ensure dependencies are current
164+
- Check that changes don't break existing plugin functionality
165+
- Verify new tests follow existing patterns in `tests/plugins/` structure
166+
167+
### Deployment Notes
168+
- Production deployment uses Dokku to github-bot.eslint.org
169+
- Health check endpoint: https://github-bot.eslint.org/ping
170+
- Webhook URL: /api/github/webhooks (Probot default)
171+
- Uses `Procfile` for production process management
172+
173+
## Development Workflow
174+
175+
1. Make changes to plugin code in `src/plugins/`
176+
2. Update or add tests in `tests/plugins/`
177+
3. Run `npm test` to verify all tests pass (NEVER CANCEL - takes ~3 seconds)
178+
4. Run `npm run lint` to check code style (NEVER CANCEL - takes ~1.5 seconds)
179+
5. Test server functionality: `npm start` and verify `/ping` responds
180+
6. For plugin changes, manually test relevant GitHub webhook scenarios if possible
181+
182+
Always follow this complete validation workflow before committing changes.

0 commit comments

Comments
 (0)