Skip to content

Commit 79064da

Browse files
egekorkanegekorkan
authored
Add AI agent instructions for repository contributors
Add comprehensive instructions for AI agents in the repository, covering development requirements, code quality standards, pull request guidelines, review criteria, and common pitfalls.
1 parent fcaa652 commit 79064da

1 file changed

Lines changed: 165 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
## **AI Agent Instructions for eclipse-thingweb/node-wot**
2+
3+
### **Repository Context**
4+
- **Project**: Eclipse Thingweb Node-WoT
5+
- **Language**: TypeScript (97.5%), JavaScript (2.4%)
6+
- **Purpose**: A fast and extensible framework to connect any device with your browser and backend applications
7+
- **Standards**: W3C Web of Things (WoT) specifications
8+
9+
---
10+
11+
## **WHEN PROVIDING CODE**
12+
13+
### **Pre-Development Requirements**
14+
1. **Read the CONTRIBUTING.md file** at https://github.com/eclipse-thingweb/node-wot/blob/master/CONTRIBUTING.md
15+
2. **Understand the W3C WoT standards** at https://www.w3.org/TR/2023/REC-wot-thing-description11-20231205/
16+
3. **Verify Eclipse Foundation compliance**:
17+
- Contributor must have an Eclipse Foundation account with GitHub ID linked
18+
- Contributor must have signed the Eclipse Contributor Agreement (ECA)
19+
20+
### **Code Quality Standards**
21+
1. **Linting & Formatting**:
22+
- Run `npm run lint` before committing
23+
- Run `npm run format` to automatically fix style issues
24+
- Ensure no ESLint warnings or errors remain
25+
- Follow the strict boolean expressions rule (use `==` or `!=` for null/undefined checks, not `if (var)`)
26+
27+
2. **Scope & Minimal Diffs**:
28+
- Keep changes limited to the specific feature/fix scope
29+
- Do not modify unrelated parts of files
30+
- Strive for the minimum git diff (fewest lines changed)
31+
- Avoid unnecessary refactoring outside the scope of work
32+
33+
3. **Testing**:
34+
- Run the full test suite before committing: `npm run test` or equivalent
35+
- Ensure all tests pass
36+
- Add tests for new features or fixes
37+
38+
4. **Special Attention for Core Changes**:
39+
- If modifying `packages/core`, understand that this impacts ALL other packages
40+
- Check if changes contradict the W3C WoT Scripting API specification: https://w3c.github.io/wot-scripting-api/
41+
- Verify all dependent packages are updated accordingly
42+
- Validate compatibility with existing protocol bindings
43+
44+
5. **Bypassing the Problem**:
45+
46+
- If you do not find a solution to the problem, do not bypass it by typecasting, ignoring the tests etc.
47+
48+
6. **Commit Requirements**:
49+
- **All commits MUST be signed** using the contributor's Eclipse Foundation account email
50+
- Configure git: `git config user.email "<eclipse-account-email>"`
51+
- Commit with `-s` flag: `git commit -s -m "<message>"`
52+
- Follow Conventional Changelog format:
53+
```
54+
<type>(<scope>): <subject>
55+
56+
<body>
57+
58+
<footer>
59+
```
60+
- **Allowed types**: `feat`, `fix`, `refactor`, `perf`, `style`, `test`, `chore`, `docs`
61+
- **Subject**: imperative mood, present tense, lowercase, no period
62+
- **Example**: `feat(binding-coap): add support for observe option`
63+
64+
### **Pull Request Requirements**
65+
1. **PR Body MUST include**:
66+
- **Explanation of AI assistance used**: Describe how AI tools assisted in generating the code, specific aspects AI helped with, and what human review/validation was performed
67+
- **Concise change description**: Exactly what was changed, why, and technical details
68+
- **Do NOT discuss**: Benefits, impact on users, or general statements about the value of the change
69+
70+
2. **Example PR Body**:
71+
```markdown
72+
## AI Assistance Summary
73+
This PR was generated with AI assistance for boilerplate code generation and structural
74+
implementation. The AI helped with [specific aspect], while human verification confirmed
75+
[what was validated].
76+
77+
## Changes
78+
- Modified `packages/binding-foo/src/foo-client.ts` to implement ProtocolClient interface
79+
- Added error handling for connection timeouts
80+
- Updated corresponding test file
81+
82+
Fixes #123
83+
```
84+
85+
3. **PR Process**:
86+
- Create feature branch from master
87+
- Do NOT merge with master while developing
88+
- If master updates are needed, rebase: `git checkout master && git pull && git checkout - && git rebase master`
89+
- Ensure CI/CD checks pass
90+
- Do NOT force push unless absolutely necessary
91+
92+
---
93+
94+
## **WHEN REVIEWING CODE**
95+
96+
### **Review Scope & Guidelines**
97+
1. **Primary Focus Areas**:
98+
- Code correctness and adherence to W3C WoT standards
99+
- Compliance with repository coding standards (ESLint, Prettier, style guide)
100+
- Proper testing and test coverage
101+
- Commit message quality and signing
102+
- PR description completeness (especially AI assistance disclosure)
103+
104+
2. **Avoid Redundancy**:
105+
- Do NOT repeat observations already in the PR author's initial summary/first comment
106+
- Read the PR description first to understand context and intent
107+
108+
3. **W3C WoT Standards Validation**:
109+
- Verify implementation matches W3C WoT Thing Description specification
110+
- Check W3C WoT Scripting API compliance for any core changes
111+
- Validate protocol binding implementations against expected interfaces
112+
113+
4. **Ecosystem Impact Assessment**:
114+
- If reviewing core changes: verify impact across all dependent packages
115+
- Check if breaking changes are properly documented in PR body
116+
- Validate that bindings still function correctly
117+
118+
### **Comment Management**
119+
1. **Consolidation Rule**:
120+
- If you find yourself writing more than 5 separate comments:
121+
- Consolidate into a single summarized comment
122+
- Organize by category (critical issues, style, suggestions)
123+
- Clearly mark blockers vs. optional improvements
124+
- Ask contributor to review and respond to the summary comment
125+
126+
2. **Comment Examples**:
127+
- ✅ **Good**: Points out specific issue with concrete fix suggestion
128+
- ❌ **Avoid**: Repeating the same point multiple times across different comments
129+
- ✅ **Good**: Consolidating multiple style issues into: "Code style issues found in 3 locations: [list]. Please run `npm run format`"
130+
131+
### **Approval Criteria**
132+
- [ ] All commits are signed with Eclipse account email
133+
- [ ] Code passes `npm run lint` and `npm run format`
134+
- [ ] All tests pass (`npm run test`)
135+
- [ ] PR body explains AI assistance and changes clearly
136+
- [ ] Conventional commit format followed
137+
- [ ] No unrelated changes to files
138+
- [ ] W3C WoT standards compliance verified
139+
- [ ] If core changes: dependent packages updated/validated
140+
- [ ] No merge conflicts with master
141+
142+
---
143+
144+
## **Key References for AI Agents**
145+
146+
| Resource | Purpose |
147+
|----------|---------|
148+
| [CONTRIBUTING.md](https://github.com/eclipse-thingweb/node-wot/blob/master/CONTRIBUTING.md) | Full contribution guidelines |
149+
| [W3C WoT Thing Description](https://www.w3.org/TR/2023/REC-wot-thing-description11-20231205/) | Core specification |
150+
| [W3C WoT Scripting API](https://w3c.github.io/wot-scripting-api/) | Required for core/API changes |
151+
| [Eclipse ECA](http://www.eclipse.org/legal/ECA.php) | Legal requirements |
152+
| [Eclipse Committer Handbook](https://www.eclipse.org/projects/handbook/) | Best practices |
153+
154+
---
155+
156+
## **Common Pitfalls to Avoid**
157+
158+
1. ❌ Unsigned commits → ✅ Always use `-s` flag with Eclipse account email
159+
2. ❌ Linting warnings → ✅ Run `npm run lint && npm run format` before commit
160+
3. ❌ Scope creep → ✅ Only modify files related to the specific change
161+
4. ❌ Missing AI disclosure → ✅ Always explain AI assistance in PR body
162+
5. ❌ Core changes without validation → ✅ Test impact on all dependent packages
163+
6. ❌ Large diffs → ✅ Strive for minimal, focused changes
164+
7. ❌ Verbose PR descriptions → ✅ Be concise and technical, not marketing-focused
165+
8. ❌ Excessive review comments → ✅ Consolidate into organized summary at 5+ comments

0 commit comments

Comments
 (0)