Skip to content

Commit 458182a

Browse files
vogellavogella
committed
Add detailed Copilot onboarding instructions for Eclipse Platform UI
Provides an automated Copilot analysis to guide follow-up tasks. Includes validation steps and links to key documentation for easier setup and future reference.
1 parent 27438b5 commit 458182a

File tree

1 file changed

+160
-0
lines changed

1 file changed

+160
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Eclipse Platform UI - Copilot Instructions
2+
3+
## Repository Overview
4+
5+
Eclipse Platform UI provides UI building blocks for Eclipse IDE and Rich Client Platform (RCP): JFace, commands, databinding, dialogs, editors, views, perspectives, and workbench. Built on SWT.
6+
7+
**Key Facts:** 127 MB, 7,675+ Java files, Maven/Tycho build, 57 bundles + 34 test bundles + 25 examples, Java 17, Maven 3.9.x
8+
9+
## Project Structure
10+
11+
### Top-Level Directories
12+
13+
```
14+
eclipse.platform.ui/
15+
├── bundles/ # 57 OSGi bundles (production code)
16+
├── tests/ # 34 test bundles
17+
├── examples/ # 25 example bundles
18+
├── features/ # Eclipse feature definitions
19+
├── releng/ # Release engineering artifacts
20+
├── docs/ # Extensive documentation (JFace, RCP, Commands, etc.)
21+
├── .github/ # GitHub workflows and CI configuration
22+
├── pom.xml # Root Maven POM
23+
└── Jenkinsfile # Jenkins CI configuration
24+
```
25+
26+
### Key Bundles
27+
28+
- `org.eclipse.ui.workbench` - Main workbench
29+
- `org.eclipse.jface` - JFace toolkit
30+
- `org.eclipse.e4.ui.*` - E4 workbench/CSS/DI
31+
- `org.eclipse.core.databinding*` - Data binding
32+
- `org.eclipse.core.commands` - Commands
33+
34+
### Bundle Structure
35+
36+
Each OSGi bundle contains: `META-INF/MANIFEST.MF` (dependencies), `build.properties` (build config), `plugin.xml` (extensions), source in `src/` or `eclipseui/`
37+
38+
## Build System - CRITICAL LIMITATIONS
39+
40+
**⚠️ IMPORTANT:** Standalone `mvn clean verify` **FAILS** - requires parent POM from `eclipse.platform.releng.aggregator`
41+
42+
**Workarounds:**
43+
- Individual bundles: `cd bundles/<bundle>; mvn clean verify -Pbuild-individual-bundles`
44+
- Full CI build: Uses aggregator project workflows
45+
- Local testing: Verify syntax/logic without full Maven build
46+
47+
**Maven Config (`.mvn/maven.config`):** `-Pbuild-individual-bundles -Dtycho.target.eager=true -Dtycho.localArtifacts=ignore`
48+
49+
**CI Profiles:** `-Pbree-libs -Papi-check -Pjavadoc` (Jenkins timeout: 80 min)
50+
51+
## Testing
52+
53+
**Test Command:** `mvn clean verify -Pbuild-individual-bundles -DskipTests=false`
54+
55+
**Properties:** `tycho.surefire.useUIHarness=true` (UI test harness), `tycho.surefire.useUIThread=true` (UI thread)
56+
57+
**Dependencies:** Install "Eclipse Test Framework" from release p2 repo for Mockito/Hamcrest
58+
59+
**Test Pattern:**
60+
```java
61+
@Before
62+
public void setUp() {
63+
fShell = new Shell(Display.getDefault());
64+
// setup
65+
}
66+
@After
67+
public void tearDown() { /* cleanup */ }
68+
@Test
69+
public void test() { /* implementation */ }
70+
```
71+
72+
## CI/GitHub Workflows
73+
74+
**Primary Workflows:**
75+
- `ci.yml` - Main build (push/PR to master, ignores docs/md), uses aggregator's mavenBuild.yml
76+
- `pr-checks.yml` - Fast checks (freeze period, merge commits, version increments)
77+
- `unit-tests.yml` - Publishes test results after CI
78+
- `codeql.yml` - Security scanning
79+
80+
**Validation Steps:**
81+
1. Compiler checks (Eclipse compiler)
82+
2. API compatibility (API tools → `**/target/apianalysis/*.xml`)
83+
3. Javadoc generation (`failOnJavadocErrors=true`)
84+
4. Unit tests (JUnit with UI harness)
85+
5. Test reports (`**/target/surefire-reports/TEST-*.xml`)
86+
6. Logs archived (`*.log,**/target/**/*.log`)
87+
88+
**CI Environment:** Java 21, xvnc for headless UI tests, quality gate DELTA=1
89+
90+
## Making Code Changes
91+
92+
**Before Starting:** Identify bundle, check `META-INF/MANIFEST.MF` for dependencies, find test bundle
93+
94+
**Common Pitfalls:**
95+
1. New dependencies → OSGi dependency issues
96+
2. API changes → Breaks compatibility (CI will fail)
97+
3. UI code not on Display thread → Crashes
98+
4. Undisposed SWT resources → Memory leaks
99+
5. Missing build.properties updates → Build failures
100+
101+
**Critical Patterns:**
102+
```java
103+
// Resource disposal
104+
Display display = Display.getDefault();
105+
Shell shell = new Shell(display);
106+
try { /* use */ } finally { shell.dispose(); }
107+
108+
// Async UI
109+
Display.getDefault().asyncExec(() -> { /* UI code */ });
110+
111+
// Data binding
112+
DataBindingContext ctx = new DataBindingContext();
113+
ctx.bindValue(
114+
WidgetProperties.text(SWT.Modify).observe(widget),
115+
BeanProperties.value("prop").observe(bean)
116+
);
117+
```
118+
119+
**Key Files:** `MANIFEST.MF` (dependencies), `plugin.xml` (extensions), `build.properties` (build), `.settings/*.prefs` (compiler)
120+
121+
## Critical Rules
122+
123+
1. Check `MANIFEST.MF` for dependencies before adding imports
124+
2. Don't break API compatibility - API tools will fail build
125+
3. Dispose SWT resources (fonts, images, shells) - system colors don't need disposal
126+
4. UI code must run on Display thread (use `asyncExec`/`syncExec`)
127+
5. Use existing test infrastructure (JUnit 4, UI harness)
128+
6. Update `build.properties` when adding files/packages
129+
7. Follow OSGi patterns - declarative services, no static dependencies
130+
131+
## Quick Reference & Documentation
132+
133+
**Docs:** `docs/JFace.md`, `docs/JFaceDataBinding.md`, `docs/Eclipse4_RCP_FAQ.md`, `docs/PlatformCommandFramework.md`
134+
**Links:** [Platform UI wiki](https://wiki.eclipse.org/Platform_UI), [Contributing](https://github.com/eclipse-platform/.github/blob/main/CONTRIBUTING.md)
135+
136+
**Root Files:** `.github/` (workflows), `.mvn/` (Maven config), `bundles/` (57), `tests/` (34), `examples/` (25), `features/`, `releng/`, `docs/`, `pom.xml`, `Jenkinsfile`
137+
138+
## Agent Guidance
139+
140+
**Trust these instructions** - validated and tested. Search only if information is incomplete or incorrect.
141+
142+
**Making Changes:**
143+
1. Identify affected bundle(s)
144+
2. Review `MANIFEST.MF` dependencies
145+
3. Find corresponding test bundle
146+
4. Make minimal, focused changes
147+
5. Update `build.properties` if adding files
148+
6. Verify OSGi manifest updates if needed
149+
150+
**Test Failures:**
151+
- Check UI test needs Display/Shell setup
152+
- Verify `useUIHarness=true` in test config
153+
- Check resource disposal
154+
- Review setup/teardown initialization
155+
156+
**Build Errors:**
157+
- "Non-resolvable parent POM" → Expected, needs aggregator parent
158+
- "Package does not exist" → Check `MANIFEST.MF` imports
159+
- "API baseline errors" → API compatibility broken
160+
- Test hangs → Missing `Display.syncExec`/`asyncExec`

0 commit comments

Comments
 (0)