Skip to content

Commit bc025bb

Browse files
Copilotjoshblackjonrohan
authored
Add comprehensive GitHub Copilot instructions for eslint-plugin-primer-react (#378)
* Initial plan * Complete comprehensive .github/copilot-instructions.md file with validated workflows Co-authored-by: joshblack <[email protected]> * Update copilot-instructions.md to reflect Node.js v20 upgrade Co-authored-by: jonrohan <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: joshblack <[email protected]> Co-authored-by: jonrohan <[email protected]>
1 parent 4594f72 commit bc025bb

File tree

1 file changed

+159
-0
lines changed

1 file changed

+159
-0
lines changed

.github/copilot-instructions.md

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# eslint-plugin-primer-react
2+
3+
ESLint plugin for Primer React components. This is a JavaScript-based ESLint plugin that provides rules for validating and auto-fixing Primer React component usage.
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+
11+
- Install Node.js v20+ (v20 is the current standard):
12+
- Check version: `node --version && npm --version`
13+
- Install dependencies: `npm ci` -- takes 60 seconds. Set timeout to 90+ seconds.
14+
- **NO BUILD STEP REQUIRED** - This is a direct JavaScript project with main entry at `src/index.js`
15+
16+
### Development Commands
17+
18+
- Run tests: `npm test` -- takes 5 seconds. Fast, no long timeout needed.
19+
- Run linting: `npm run lint` -- takes 1.5 seconds. Very fast.
20+
- Run markdown linting: `npm run lint:md` -- takes under 1 second. Very fast.
21+
- Check formatting: `npm run format:check` -- takes 0.5 seconds. Very fast.
22+
- Fix formatting: `npm run format` -- applies Prettier formatting fixes.
23+
24+
### Testing and Validation
25+
26+
- **ALWAYS** run `npm test` after making changes to rules - tests run in 5 seconds
27+
- **ALWAYS** run `npm run lint && npm run lint:md` before committing - both complete in under 3 seconds total
28+
- **ALWAYS** run `npm run format:check` to verify formatting - completes in 0.5 seconds
29+
- All validation commands are very fast - no need for long timeouts or cancellation warnings
30+
31+
### Manual Rule Testing
32+
33+
You can manually test individual rules using this pattern:
34+
35+
```bash
36+
node -e "
37+
const rule = require('./src/rules/RULE_NAME');
38+
const {RuleTester} = require('eslint');
39+
const ruleTester = new RuleTester({
40+
parserOptions: {
41+
ecmaVersion: 'latest',
42+
sourceType: 'module',
43+
ecmaFeatures: { jsx: true }
44+
}
45+
});
46+
ruleTester.run('test', rule, {
47+
valid: [{ code: 'VALID_CODE_HERE' }],
48+
invalid: [{ code: 'INVALID_CODE_HERE', errors: [{ messageId: 'MESSAGE_ID' }] }]
49+
});
50+
"
51+
```
52+
53+
## Repository Structure and Navigation
54+
55+
### Key Directories
56+
57+
- `src/rules/` - ESLint rule implementations
58+
- `src/rules/__tests__/` - Jest tests for each rule using ESLint RuleTester
59+
- `docs/rules/` - Markdown documentation for each rule
60+
- `src/configs/` - ESLint configuration presets (e.g., recommended.js)
61+
- `src/utils/` - Utility functions shared across rules
62+
- `.github/workflows/` - CI pipeline definitions
63+
64+
### Important Files
65+
66+
- `src/index.js` - Main entry point, exports all rules and configs
67+
- `package.json` - Scripts and dependencies (no build scripts needed)
68+
- `jest.config.js` - Jest test configuration
69+
- `.eslintrc.js` - ESLint configuration for the project itself
70+
- `.nvmrc` - Node.js version specification (v20)
71+
72+
### Rule Development Pattern
73+
74+
Each rule follows this structure:
75+
76+
1. Rule implementation: `src/rules/rule-name.js`
77+
2. Test file: `src/rules/__tests__/rule-name.test.js`
78+
3. Documentation: `docs/rules/rule-name.md`
79+
4. Export from: `src/index.js` (add to rules object)
80+
5. Optional: Add to `src/configs/recommended.js` if should be in recommended preset
81+
82+
## Validation Scenarios
83+
84+
### After Making Rule Changes
85+
86+
1. Run the rule's specific test: `npm test -- --testNamePattern="rule-name"`
87+
2. Run all tests: `npm test` (5 seconds)
88+
3. Test the rule manually using the Node.js snippet pattern above
89+
4. Verify the rule is exported properly from `src/index.js`
90+
91+
### Before Committing
92+
93+
1. `npm run lint` - JavaScript linting (1.5 seconds)
94+
2. `npm run lint:md` - Markdown linting (<1 second)
95+
3. `npm run format:check` - Formatting validation (0.5 seconds)
96+
4. `npm test` - Full test suite (5 seconds)
97+
98+
### Testing Plugin Integration
99+
100+
The plugin can be tested by:
101+
102+
1. Using manual Node.js rule testing (shown above)
103+
2. Running existing test suite which validates all rules
104+
3. Creating test files and using ESLint RuleTester in the **tests** files
105+
106+
## Common Development Tasks
107+
108+
### Adding a New Rule
109+
110+
1. Create rule implementation: `src/rules/new-rule-name.js`
111+
2. Create test file: `src/rules/__tests__/new-rule-name.test.js`
112+
3. Add to exports in `src/index.js`
113+
4. Create documentation: `docs/rules/new-rule-name.md`
114+
5. Optionally add to `src/configs/recommended.js`
115+
6. Run tests: `npm test`
116+
7. Run linting: `npm run lint`
117+
118+
### Modifying Existing Rules
119+
120+
1. Edit rule in `src/rules/rule-name.js`
121+
2. Update tests in `src/rules/__tests__/rule-name.test.js`
122+
3. Update documentation in `docs/rules/rule-name.md` if needed
123+
4. Run tests: `npm test`
124+
5. Test manually using Node.js snippet if needed
125+
126+
### Working with Changesets (for releases)
127+
128+
- `npx changeset` - Create a changeset for changes
129+
- `npx changeset status` - Check changeset status
130+
- Changesets are used for versioning and publishing to npm
131+
132+
## Troubleshooting
133+
134+
### Common Issues
135+
136+
- **Node.js version**: Use Node.js v20+ (v20 is the current standard)
137+
- **Dependencies**: Always use `npm ci` instead of `npm install` for consistent installs
138+
- **Test failures**: Run `npm test` to see specific failures - tests are fast and detailed
139+
- **Lint failures**: Run `npm run lint` and `npm run lint:md` to see specific issues
140+
- **Format issues**: Run `npm run format` to auto-fix formatting
141+
142+
### Rule Testing Issues
143+
144+
- Use the RuleTester pattern shown above for manual testing
145+
- Check that messageId in tests matches the rule's meta.messages
146+
- Verify JSX parsing works by including ecmaFeatures.jsx in parserOptions
147+
148+
## Command Reference
149+
150+
Essential commands and their typical execution times:
151+
152+
- `npm ci` - Install dependencies (60 seconds)
153+
- `npm test` - Run all tests (5 seconds)
154+
- `npm run lint` - Lint JavaScript (1.5 seconds)
155+
- `npm run lint:md` - Lint Markdown (<1 second)
156+
- `npm run format:check` - Check formatting (0.5 seconds)
157+
- `npm run format` - Fix formatting (similar time)
158+
159+
All commands except `npm ci` are very fast. No need for extended timeouts or cancellation warnings on validation commands.

0 commit comments

Comments
 (0)