diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index 42b8038a110..00000000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,160 +0,0 @@ -# Eclipse Platform UI - Copilot Instructions - -## Repository Overview - -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. - -**Key Facts:** 127 MB, 7,675+ Java files, Maven/Tycho build, 57 bundles + 34 test bundles + 25 examples, Java 17, Maven 3.9.x - -## Project Structure - -### Top-Level Directories - -``` -eclipse.platform.ui/ -├── bundles/ # 57 OSGi bundles (production code) -├── tests/ # 34 test bundles -├── examples/ # 25 example bundles -├── features/ # Eclipse feature definitions -├── releng/ # Release engineering artifacts -├── docs/ # Extensive documentation (JFace, RCP, Commands, etc.) -├── .github/ # GitHub workflows and CI configuration -├── pom.xml # Root Maven POM -└── Jenkinsfile # Jenkins CI configuration -``` - -### Key Bundles - -- `org.eclipse.ui.workbench` - Main workbench -- `org.eclipse.jface` - JFace toolkit -- `org.eclipse.e4.ui.*` - E4 workbench/CSS/DI -- `org.eclipse.core.databinding*` - Data binding -- `org.eclipse.core.commands` - Commands - -### Bundle Structure - -Each OSGi bundle contains: `META-INF/MANIFEST.MF` (dependencies), `build.properties` (build config), `plugin.xml` (extensions), source in `src/` or `eclipseui/` - -## Build System - CRITICAL LIMITATIONS - -**⚠️ IMPORTANT:** Standalone `mvn clean verify` **FAILS** - requires parent POM from `eclipse.platform.releng.aggregator` - -**Workarounds:** -- Individual bundles: `cd bundles/; mvn clean verify -Pbuild-individual-bundles` -- Full CI build: Uses aggregator project workflows -- Local testing: Verify syntax/logic without full Maven build - -**Maven Config (`.mvn/maven.config`):** `-Pbuild-individual-bundles -Dtycho.target.eager=true -Dtycho.localArtifacts=ignore` - -**CI Profiles:** `-Pbree-libs -Papi-check -Pjavadoc` (Jenkins timeout: 80 min) - -## Testing - -**Test Command:** `mvn clean verify -Pbuild-individual-bundles -DskipTests=false` - -**Properties:** `tycho.surefire.useUIHarness=true` (UI test harness), `tycho.surefire.useUIThread=true` (UI thread) - -**Dependencies:** Install "Eclipse Test Framework" from release p2 repo for Mockito/Hamcrest - -**Test Pattern:** -```java -@Before -public void setUp() { - fShell = new Shell(Display.getDefault()); - // setup -} -@After -public void tearDown() { /* cleanup */ } -@Test -public void test() { /* implementation */ } -``` - -## CI/GitHub Workflows - -**Primary Workflows:** -- `ci.yml` - Main build (push/PR to master, ignores docs/md), uses aggregator's mavenBuild.yml -- `pr-checks.yml` - Fast checks (freeze period, merge commits, version increments) -- `unit-tests.yml` - Publishes test results after CI -- `codeql.yml` - Security scanning - -**Validation Steps:** -1. Compiler checks (Eclipse compiler) -2. API compatibility (API tools → `**/target/apianalysis/*.xml`) -3. Javadoc generation (`failOnJavadocErrors=true`) -4. Unit tests (JUnit with UI harness) -5. Test reports (`**/target/surefire-reports/TEST-*.xml`) -6. Logs archived (`*.log,**/target/**/*.log`) - -**CI Environment:** Java 21, xvnc for headless UI tests, quality gate DELTA=1 - -## Making Code Changes - -**Before Starting:** Identify bundle, check `META-INF/MANIFEST.MF` for dependencies, find test bundle - -**Common Pitfalls:** -1. New dependencies → OSGi dependency issues -2. API changes → Breaks compatibility (CI will fail) -3. UI code not on Display thread → Crashes -4. Undisposed SWT resources → Memory leaks -5. Missing build.properties updates → Build failures - -**Critical Patterns:** -```java -// Resource disposal -Display display = Display.getDefault(); -Shell shell = new Shell(display); -try { /* use */ } finally { shell.dispose(); } - -// Async UI -Display.getDefault().asyncExec(() -> { /* UI code */ }); - -// Data binding -DataBindingContext ctx = new DataBindingContext(); -ctx.bindValue( - WidgetProperties.text(SWT.Modify).observe(widget), - BeanProperties.value("prop").observe(bean) -); -``` - -**Key Files:** `MANIFEST.MF` (dependencies), `plugin.xml` (extensions), `build.properties` (build), `.settings/*.prefs` (compiler) - -## Critical Rules - -1. Check `MANIFEST.MF` for dependencies before adding imports -2. Don't break API compatibility - API tools will fail build -3. Dispose SWT resources (fonts, images, shells) - system colors don't need disposal -4. UI code must run on Display thread (use `asyncExec`/`syncExec`) -5. Use existing test infrastructure (JUnit 4, UI harness) -6. Update `build.properties` when adding files/packages -7. Follow OSGi patterns - declarative services, no static dependencies - -## Quick Reference & Documentation - -**Docs:** `docs/JFace.md`, `docs/JFaceDataBinding.md`, `docs/Eclipse4_RCP_FAQ.md`, `docs/PlatformCommandFramework.md` -**Links:** [Platform UI wiki](https://wiki.eclipse.org/Platform_UI), [Contributing](https://github.com/eclipse-platform/.github/blob/main/CONTRIBUTING.md) - -**Root Files:** `.github/` (workflows), `.mvn/` (Maven config), `bundles/` (57), `tests/` (34), `examples/` (25), `features/`, `releng/`, `docs/`, `pom.xml`, `Jenkinsfile` - -## Agent Guidance - -**Trust these instructions** - validated and tested. Search only if information is incomplete or incorrect. - -**Making Changes:** -1. Identify affected bundle(s) -2. Review `MANIFEST.MF` dependencies -3. Find corresponding test bundle -4. Make minimal, focused changes -5. Update `build.properties` if adding files -6. Verify OSGi manifest updates if needed - -**Test Failures:** -- Check UI test needs Display/Shell setup -- Verify `useUIHarness=true` in test config -- Check resource disposal -- Review setup/teardown initialization - -**Build Errors:** -- "Non-resolvable parent POM" → Expected, needs aggregator parent -- "Package does not exist" → Check `MANIFEST.MF` imports -- "API baseline errors" → API compatibility broken -- Test hangs → Missing `Display.syncExec`/`asyncExec` diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..4cc513fb396 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,350 @@ +# AGENTS.md + +This file provides guidance to AI Agents (claude-code, codex, gemini cli, ...) when working with code in this repository. + +## Repository Overview + +Eclipse Platform UI provides the UI building blocks for Eclipse IDE and Eclipse Rich Client Platform (RCP). This includes JFace, workbench, commands framework, data binding, dialogs, editors, views, perspectives, and more. Built on top of SWT (Eclipse Standard Widget Toolkit). + +**Key Facts:** +- **Language:** Java 17 +- **Build System:** Maven 3.9.x with Tycho (OSGi/Eclipse plugin build) +- **Architecture:** OSGi bundles, E4 application model + +## Project Structure + +``` +eclipse.platform.ui/ +├── bundles/ # OSGi bundles (production code) +│ ├── org.eclipse.ui.workbench # Main workbench implementation +│ ├── org.eclipse.jface # JFace toolkit (viewers, dialogs, etc.) +│ ├── org.eclipse.jface.databinding # Data binding framework +│ ├── org.eclipse.jface.text # Text editing framework +│ ├── org.eclipse.core.commands # Commands framework +│ ├── org.eclipse.core.databinding* # Core data binding +│ ├── org.eclipse.e4.ui.* # E4 workbench, CSS, DI, model +│ └── org.eclipse.ui.* # UI components (IDE, editors, views, etc.) +├── tests/ # Test bundles (mirror structure of bundles/) +├── examples/ # Example bundles +├── features/ # Eclipse feature definitions +├── releng/ # Release engineering artifacts +├── docs/ # Documentation (JFace, RCP, Commands, etc.) +└── .github/ # GitHub workflows and CI configuration +``` + +### Key Architectural Components + +**E4 Platform (Modern):** +- `org.eclipse.e4.ui.model.workbench` - E4 application model +- `org.eclipse.e4.ui.workbench*` - E4 workbench implementation +- `org.eclipse.e4.ui.di` - Dependency injection +- `org.eclipse.e4.ui.css.*` - CSS styling engine +- `org.eclipse.e4.core.commands` - Command framework + +**JFace Toolkit:** +- `org.eclipse.jface` - Viewers, dialogs, resources, actions +- `org.eclipse.jface.databinding` - Data binding for UI +- `org.eclipse.jface.text` - Text editing infrastructure + +**Legacy Workbench (3.x compatibility):** +- `org.eclipse.ui.workbench` - Workbench implementation +- `org.eclipse.ui.ide` - IDE-specific components +- `org.eclipse.ui.editors` - Editor framework + +### OSGi Bundle Structure + +Each bundle contains: +- `META-INF/MANIFEST.MF` - Bundle metadata and dependencies +- `build.properties` - Build configuration (what to include in binary) +- `plugin.xml` - Extension point declarations and contributions (optional) +- `src/` or `eclipseui/` - Java source code +- `.settings/` - Eclipse compiler settings + +## Build System + +### Critical Limitation + +**⚠️ IMPORTANT:** Standalone `mvn clean verify` at repository root **WILL FAIL** with "Non-resolvable parent POM" error. This repository requires a parent POM from `eclipse.platform.releng.aggregator`. + +### Building Individual Bundles + +Use the `-Pbuild-individual-bundles` profile: + +```bash +# Compile a single bundle +cd bundles/org.eclipse.jface +mvn clean compile -Pbuild-individual-bundles + +# Run tests for a single bundle +cd tests/org.eclipse.jface.tests +mvn clean verify -Pbuild-individual-bundles + +# Run specific test class +mvn test -Pbuild-individual-bundles -Dtest=ViewerTestClass +``` + +### Maven Configuration + +Default config in `.mvn/maven.config`: +- `-Pbuild-individual-bundles` - Enable individual bundle builds +- `-Dtycho.target.eager=true` - Eager target resolution +- `-Dtycho.localArtifacts=ignore` - Ignore local artifacts + +### Test Properties + +From `pom.xml`: +- `tycho.surefire.useUIHarness=true` - Use Eclipse UI test harness +- `tycho.surefire.useUIThread=true` - Run tests on UI thread +- `failOnJavadocErrors=true` - Fail build on Javadoc errors + +## Testing + +### Running Tests + +**⚠️ IMPORTANT:** Use `mvn verify` (NOT `mvn test`) for Tycho projects. Due to Maven Tycho lifecycle binding, tests run in the `integration-test` phase, not the `test` phase. Running `mvn test` will NOT execute tests. + +```bash +# Run all tests in a specific test bundle +cd tests/org.eclipse.jface.tests +mvn clean verify -Pbuild-individual-bundles + +# Run without clean (faster if no changes to dependencies) +mvn verify -Pbuild-individual-bundles + +# Run tests for a specific test bundle from repository root +mvn clean verify -pl :org.eclipse.jface.tests -Pbuild-individual-bundles + +# Run specific test class within a bundle +cd tests/org.eclipse.jface.tests +mvn clean verify -Pbuild-individual-bundles -Dtest=StructuredViewerTest + +# Skip tests during compilation +mvn clean compile -Pbuild-individual-bundles -DskipTests +``` + +**Finding test bundles:** Test bundles mirror production bundles: +- Production: `bundles/org.eclipse.jface` +- Tests: `tests/org.eclipse.jface.tests` + +### JUnit Guidelines + +- Prefer JUnit 5 (`org.junit.jupiter.api.*`) for new tests +- Use `@BeforeEach`/`@AfterEach` instead of `@Before`/`@After` +- Use `@Disabled` instead of `@Ignore` +- Use `Assertions.*` instead of `Assert.*` +- JUnit 3 usage is limited to compatibility helpers (e.g., `org.eclipse.ui.tests.harness`) + +**Common test pattern:** +```java +@BeforeEach +public void setUp() { + fDisplay = Display.getDefault(); + fShell = new Shell(fDisplay); +} + +@AfterEach +public void tearDown() { + if (fShell != null) { + fShell.dispose(); + } +} + +@Test +public void testSomething() { + // Test implementation + Assertions.assertEquals(expected, actual); +} +``` + +## Common Development Commands + +### Compilation + +```bash +# Compile single bundle +mvn clean compile -pl :bundle-artifact-id -Pbuild-individual-bundles -q + +# Compile and run tests +mvn clean test -pl :bundle-artifact-id -Pbuild-individual-bundles +``` + +### Finding Code + +```bash +# Find test files for a bundle +ls tests/org.eclipse.jface.tests/src + +# Find bundle MANIFEST +cat bundles/org.eclipse.jface/META-INF/MANIFEST.MF + +# Search for specific code pattern +grep -r "pattern" bundles/org.eclipse.jface/src +``` + +## Critical Development Rules + +### 1. OSGi Dependencies + +**Always check `META-INF/MANIFEST.MF` before adding imports.** If a package is not in `Import-Package` or `Require-Bundle`, the import will fail at runtime. + +``` +Require-Bundle: org.eclipse.core.runtime, + org.eclipse.swt, + org.eclipse.jface +Import-Package: org.osgi.service.event +``` + +### 2. SWT Resource Disposal + +**Must dispose SWT resources** (except system colors/fonts): + +```java +// CORRECT - dispose in finally +Shell shell = new Shell(); +try { + // use shell +} finally { + shell.dispose(); +} + +// CORRECT - dispose custom colors/fonts/images +Color color = new Color(display, 255, 0, 0); +try { + // use color +} finally { + color.dispose(); +} + +// INCORRECT - system resources don't need disposal +Color systemColor = display.getSystemColor(SWT.COLOR_RED); +// No dispose needed +``` + +### 3. UI Thread Requirements + +**All SWT/JFace UI code must run on the Display thread:** + +```java +// Run asynchronously on UI thread +Display.getDefault().asyncExec(() -> { + label.setText("Updated"); +}); + +// Run synchronously (blocks until complete) +Display.getDefault().syncExec(() -> { + button.setEnabled(false); +}); + +// Check if on UI thread +if (Display.getCurrent() != null) { + // Already on UI thread +} else { + // Need to use asyncExec/syncExec +} +``` + +### 4. API Compatibility + +**Do not break API compatibility.** The build includes API tools that verify: +- No removal of public API +- No changes to method signatures +- No changes to class hierarchies + +Breaking changes will fail CI with errors in `**/target/apianalysis/*.xml`. + +### 5. Update build.properties + +When adding new files or packages, update `build.properties`: + +```properties +# Include in binary build +bin.includes = plugin.xml,\ + META-INF/,\ + .,\ + icons/ + +# Source folders +source.. = src/ + +# Output folder +output.. = bin/ +``` + +## Common Patterns + +### Data Binding + +```java +DataBindingContext ctx = new DataBindingContext(); + +// Bind widget to model +ctx.bindValue( + WidgetProperties.text(SWT.Modify).observe(textWidget), + BeanProperties.value("propertyName").observe(model) +); + +// Dispose when done +ctx.dispose(); +``` + +### JFace Viewers + +```java +TableViewer viewer = new TableViewer(parent, SWT.MULTI | SWT.H_SCROLL | SWT.V_SCROLL); +viewer.setContentProvider(ArrayContentProvider.getInstance()); +viewer.setLabelProvider(new LabelProvider() { + @Override + public String getText(Object element) { + return element.toString(); + } +}); +viewer.setInput(myList); +``` + +### Eclipse Commands + +Commands are defined in `plugin.xml` and handled via handlers: + +```java +@Execute +public void execute(IEclipseContext context) { + // Command implementation +} +``` + +## CI/GitHub Workflows + +- CI definition: `.github/workflows/ci.yml` (runs full aggregator build) +- PRs are gated by: compiler checks, API compatibility, Javadoc, and unit/UI tests +- UI tests run with the Eclipse UI harness in headless mode + +## Troubleshooting + +### "Non-resolvable parent POM" +Expected when running `mvn verify` at root. Use `-Pbuild-individual-bundles` for individual bundles. + +### "Package does not exist" +Check `META-INF/MANIFEST.MF` - add missing package to `Import-Package` or bundle to `Require-Bundle`. + +### "API baseline errors" +You've broken API compatibility. Revert the breaking change or mark it appropriately. + +### Test hangs +UI tests must run on Display thread. Use `Display.asyncExec()` or ensure `useUIHarness=true`. + +### "Widget is disposed" +Attempting to access disposed SWT widget. Check disposal order and lifecycle. + +## Documentation + +Key docs in `docs/` directory: +- `JFace.md` - JFace framework overview +- `JFaceDataBinding.md` - Data binding guide +- `Eclipse4_RCP_FAQ.md` - E4 RCP frequently asked questions +- `PlatformCommandFramework.md` - Command framework +- `CSS.md` - CSS styling for E4 + +External links: +- [Platform UI Wiki](https://wiki.eclipse.org/Platform_UI) +- [Contributing Guide](https://github.com/eclipse-platform/.github/blob/main/CONTRIBUTING.md) +- [Eclipse Platform Project](https://projects.eclipse.org/projects/eclipse.platform) diff --git a/CLAUDE.md b/CLAUDE.md index 73571ba21a6..eef4bd20cf9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,365 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Repository Overview - -Eclipse Platform UI provides the UI building blocks for Eclipse IDE and Eclipse Rich Client Platform (RCP). This includes JFace, workbench, commands framework, data binding, dialogs, editors, views, perspectives, and more. Built on top of SWT (Eclipse Standard Widget Toolkit). - -**Key Facts:** -- **Language:** Java 17 -- **Build System:** Maven 3.9.x with Tycho (OSGi/Eclipse plugin build) -- **Architecture:** OSGi bundles, E4 application model -- **Size:** 127 MB, 7,675+ Java files -- **Structure:** 57 production bundles + 34 test bundles + 25 examples - -## Project Structure - -``` -eclipse.platform.ui/ -├── bundles/ # 57 OSGi bundles (production code) -│ ├── org.eclipse.ui.workbench # Main workbench implementation -│ ├── org.eclipse.jface # JFace toolkit (viewers, dialogs, etc.) -│ ├── org.eclipse.jface.databinding # Data binding framework -│ ├── org.eclipse.jface.text # Text editing framework -│ ├── org.eclipse.core.commands # Commands framework -│ ├── org.eclipse.core.databinding* # Core data binding -│ ├── org.eclipse.e4.ui.* # E4 workbench, CSS, DI, model -│ └── org.eclipse.ui.* # UI components (IDE, editors, views, etc.) -├── tests/ # 34 test bundles (mirror structure of bundles/) -├── examples/ # 25 example bundles -├── features/ # Eclipse feature definitions -├── releng/ # Release engineering artifacts -├── docs/ # Documentation (JFace, RCP, Commands, etc.) -└── .github/ # GitHub workflows and CI configuration -``` - -### Key Architectural Components - -**E4 Platform (Modern):** -- `org.eclipse.e4.ui.model.workbench` - E4 application model -- `org.eclipse.e4.ui.workbench*` - E4 workbench implementation -- `org.eclipse.e4.ui.di` - Dependency injection -- `org.eclipse.e4.ui.css.*` - CSS styling engine -- `org.eclipse.e4.core.commands` - Command framework - -**JFace Toolkit:** -- `org.eclipse.jface` - Viewers, dialogs, resources, actions -- `org.eclipse.jface.databinding` - Data binding for UI -- `org.eclipse.jface.text` - Text editing infrastructure - -**Legacy Workbench (3.x compatibility):** -- `org.eclipse.ui.workbench` - Workbench implementation -- `org.eclipse.ui.ide` - IDE-specific components -- `org.eclipse.ui.editors` - Editor framework - -### OSGi Bundle Structure - -Each bundle contains: -- `META-INF/MANIFEST.MF` - Bundle metadata and dependencies -- `build.properties` - Build configuration (what to include in binary) -- `plugin.xml` - Extension point declarations and contributions (optional) -- `src/` or `eclipseui/` - Java source code -- `.settings/` - Eclipse compiler settings - -## Build System - -### Critical Limitation - -**⚠️ IMPORTANT:** Standalone `mvn clean verify` at repository root **WILL FAIL** with "Non-resolvable parent POM" error. This repository requires a parent POM from `eclipse.platform.releng.aggregator`. - -### Building Individual Bundles - -Use the `-Pbuild-individual-bundles` profile: - -```bash -# Compile a single bundle -cd bundles/org.eclipse.jface -mvn clean compile -Pbuild-individual-bundles - -# Run tests for a single bundle -cd tests/org.eclipse.jface.tests -mvn clean verify -Pbuild-individual-bundles - -# Run specific test class -mvn test -Pbuild-individual-bundles -Dtest=ViewerTestClass -``` - -### Maven Configuration - -Default config in `.mvn/maven.config`: -- `-Pbuild-individual-bundles` - Enable individual bundle builds -- `-Dtycho.target.eager=true` - Eager target resolution -- `-Dtycho.localArtifacts=ignore` - Ignore local artifacts - -### Test Properties - -From `pom.xml`: -- `tycho.surefire.useUIHarness=true` - Use Eclipse UI test harness -- `tycho.surefire.useUIThread=true` - Run tests on UI thread -- `failOnJavadocErrors=true` - Fail build on Javadoc errors - -## Testing - -### Running Tests - -**⚠️ IMPORTANT:** Use `mvn verify` (NOT `mvn test`) for Tycho projects. Due to Maven Tycho lifecycle binding, tests run in the `integration-test` phase, not the `test` phase. Running `mvn test` will NOT execute tests. - -```bash -# Run all tests in a specific test bundle -cd tests/org.eclipse.jface.tests -mvn clean verify -Pbuild-individual-bundles - -# Run without clean (faster if no changes to dependencies) -mvn verify -Pbuild-individual-bundles - -# Run tests for a specific test bundle from repository root -mvn clean verify -pl :org.eclipse.jface.tests -Pbuild-individual-bundles - -# Run specific test class within a bundle -cd tests/org.eclipse.jface.tests -mvn clean verify -Pbuild-individual-bundles -Dtest=StructuredViewerTest - -# Skip tests during compilation -mvn clean compile -Pbuild-individual-bundles -DskipTests -``` - -**Finding test bundles:** Test bundles mirror production bundles: -- Production: `bundles/org.eclipse.jface` -- Tests: `tests/org.eclipse.jface.tests` - -### JUnit Version Status (October 2025) - -**Current Migration State:** -- **JUnit 5 (Modern):** 7 bundles fully migrated, 5 partially migrated -- **JUnit 4 (Current):** 11 bundles ready for migration, majority of tests -- **JUnit 3 (Legacy):** Only in `org.eclipse.ui.tests.harness` as compatibility bridge - -**When writing new tests:** -- Prefer JUnit 5 (`org.junit.jupiter.api.*`) for new tests -- Use `@BeforeEach`/`@AfterEach` instead of `@Before`/`@After` -- Use `@Disabled` instead of `@Ignore` -- Use `Assertions.*` instead of `Assert.*` - -**Common test pattern:** -```java -@BeforeEach -public void setUp() { - fDisplay = Display.getDefault(); - fShell = new Shell(fDisplay); -} - -@AfterEach -public void tearDown() { - if (fShell != null) { - fShell.dispose(); - } -} - -@Test -public void testSomething() { - // Test implementation - Assertions.assertEquals(expected, actual); -} -``` - -## Common Development Commands - -### Compilation - -```bash -# Compile single bundle -mvn clean compile -pl :bundle-artifact-id -Pbuild-individual-bundles -q - -# Compile and run tests -mvn clean test -pl :bundle-artifact-id -Pbuild-individual-bundles -``` - -### Finding Code - -```bash -# Find test files for a bundle -ls tests/org.eclipse.jface.tests/src - -# Find bundle MANIFEST -cat bundles/org.eclipse.jface/META-INF/MANIFEST.MF - -# Search for specific code pattern -grep -r "pattern" bundles/org.eclipse.jface/src -``` - -## Critical Development Rules - -### 1. OSGi Dependencies - -**Always check `META-INF/MANIFEST.MF` before adding imports.** If a package is not in `Import-Package` or `Require-Bundle`, the import will fail at runtime. - -``` -Require-Bundle: org.eclipse.core.runtime, - org.eclipse.swt, - org.eclipse.jface -Import-Package: org.osgi.service.event -``` - -### 2. SWT Resource Disposal - -**Must dispose SWT resources** (except system colors/fonts): - -```java -// CORRECT - dispose in finally -Shell shell = new Shell(); -try { - // use shell -} finally { - shell.dispose(); -} - -// CORRECT - dispose custom colors/fonts/images -Color color = new Color(display, 255, 0, 0); -try { - // use color -} finally { - color.dispose(); -} - -// INCORRECT - system resources don't need disposal -Color systemColor = display.getSystemColor(SWT.COLOR_RED); -// No dispose needed -``` - -### 3. UI Thread Requirements - -**All SWT/JFace UI code must run on the Display thread:** - -```java -// Run asynchronously on UI thread -Display.getDefault().asyncExec(() -> { - label.setText("Updated"); -}); - -// Run synchronously (blocks until complete) -Display.getDefault().syncExec(() -> { - button.setEnabled(false); -}); - -// Check if on UI thread -if (Display.getCurrent() != null) { - // Already on UI thread -} else { - // Need to use asyncExec/syncExec -} -``` - -### 4. API Compatibility - -**Do not break API compatibility.** The build includes API tools that verify: -- No removal of public API -- No changes to method signatures -- No changes to class hierarchies - -Breaking changes will fail CI with errors in `**/target/apianalysis/*.xml`. - -### 5. Update build.properties - -When adding new files or packages, update `build.properties`: - -```properties -# Include in binary build -bin.includes = plugin.xml,\ - META-INF/,\ - .,\ - icons/ - -# Source folders -source.. = src/ - -# Output folder -output.. = bin/ -``` - -## Common Patterns - -### Data Binding - -```java -DataBindingContext ctx = new DataBindingContext(); - -// Bind widget to model -ctx.bindValue( - WidgetProperties.text(SWT.Modify).observe(textWidget), - BeanProperties.value("propertyName").observe(model) -); - -// Dispose when done -ctx.dispose(); -``` - -### JFace Viewers - -```java -TableViewer viewer = new TableViewer(parent, SWT.MULTI | SWT.H_SCROLL | SWT.V_SCROLL); -viewer.setContentProvider(ArrayContentProvider.getInstance()); -viewer.setLabelProvider(new LabelProvider() { - @Override - public String getText(Object element) { - return element.toString(); - } -}); -viewer.setInput(myList); -``` - -### Eclipse Commands - -Commands are defined in `plugin.xml` and handled via handlers: - -```java -@Execute -public void execute(IEclipseContext context) { - // Command implementation -} -``` - -## CI/GitHub Workflows - -**Primary workflow:** `.github/workflows/ci.yml` -- Triggers on push/PR to master (ignores `docs/` and `*.md`) -- Uses `eclipse.platform.releng.aggregator` for full build -- Runs on Java 21 with xvnc for headless UI tests - -**Validation steps:** -1. Compiler checks (Eclipse compiler) -2. API compatibility (API tools) -3. Javadoc generation -4. Unit tests (JUnit with UI harness) -5. Test reports published - -## Troubleshooting - -### "Non-resolvable parent POM" -Expected when running `mvn verify` at root. Use `-Pbuild-individual-bundles` for individual bundles. - -### "Package does not exist" -Check `META-INF/MANIFEST.MF` - add missing package to `Import-Package` or bundle to `Require-Bundle`. - -### "API baseline errors" -You've broken API compatibility. Revert the breaking change or mark it appropriately. - -### Test hangs -UI tests must run on Display thread. Use `Display.asyncExec()` or ensure `useUIHarness=true`. - -### "Widget is disposed" -Attempting to access disposed SWT widget. Check disposal order and lifecycle. - -## Documentation - -Key docs in `docs/` directory: -- `JFace.md` - JFace framework overview -- `JFaceDataBinding.md` - Data binding guide -- `Eclipse4_RCP_FAQ.md` - E4 RCP frequently asked questions -- `PlatformCommandFramework.md` - Command framework -- `CSS.md` - CSS styling for E4 - -External links: -- [Platform UI Wiki](https://wiki.eclipse.org/Platform_UI) -- [Contributing Guide](https://github.com/eclipse-platform/.github/blob/main/CONTRIBUTING.md) -- [Eclipse Platform Project](https://projects.eclipse.org/projects/eclipse.platform) +@AGENTS.md \ No newline at end of file