Add Eclipse 4 Migration Guide and Model Documentation for E3 to E4 RCP Application Migration

[Copilot]

Overview

This PR adds comprehensive Eclipse 4 documentation to help developers migrate Eclipse 3.x RCP applications to the Eclipse 4 application model. The documentation addresses a gap in the current documentation by providing centralized, up-to-date migration information directly in the repository.

Motivation

While there are various online resources about E3 to E4 migration, they are often:

• Too generic and broad for practical use
• Hard to find and scattered across multiple sources
• Potentially outdated and not evolving with the codebase

By including the migration guide in this repository, we ensure the documentation:

• Evolves with the code through version control
• Remains discoverable and accessible
• Can be maintained by the community
• Serves as a resource for both human developers and AI agents

What's Included

Eclipse4_Migration.md

The new migration guide provides:

1. Prerequisites and Setup

• Required MANIFEST.MF dependencies (using jakarta annotations and inject)
• Annotation support configuration
• Preserve Element IDs - Important note that E3 and E4 IDs must match for compatibility
• Creating Model Fragments - Detailed instructions on creating and registering fragment.e4xmi files

2. Component-Specific Migration Guides

Each section includes E3 approach, E4 counterpart, and step-by-step migration instructions:

Migrate a Command

• E3: org.eclipse.ui.commands extension point in plugin.xml
• E4: MCommand elements in fragment.e4xmi
• 6-step migration process

Migrate a Handler

• E3: org.eclipse.ui.handlers extension point with AbstractHandler
• E4: Dependency injection with @execute and @CanExecute annotations
• 7-step migration process
• Common injection patterns for handlers
• Important best practice: Always inject in methods (@Execute/@CanExecute) rather than fields for most recent context values

Migrate a View

• E3: org.eclipse.ui.views extension point with ViewPart
• E4: PartDescriptor with @PostConstruct and @Focus annotations
• 7-step migration process
• Common view injection patterns

Migrate a Menu

• E3: org.eclipse.ui.menus extension point
• E4: MenuContribution elements in fragment.e4xmi
• Separate guidance for main menus, toolbars, and context menus
• Visibility and enablement patterns

3. Practical Guidance

• Testing your migration (launch configuration, verification, debugging)
• Common migration pitfalls and solutions
• Links to related documentation

Eclipse4_Model.md

New comprehensive documentation for contributing to the E4 application model:

• Model fragments creation and structure
• Types of contributions (Commands, Handlers, Parts, Menus, Key Bindings, Addons)
• String model fragments with detailed examples
• Importing model elements across fragments
• Element IDs and best practices
• Application model structure overview
• Best practices for model contributions

This migrates content previously only available on the Eclipse Wiki to ensure it evolves with the codebase.

Additional Changes

• Updated docs/Eclipse4_RCP_FAQ.md to cross-reference the new migration guide at the beginning of the "Adopting the Eclipse 4 Application Platform" section
• All code examples use jakarta.annotation and jakarta.inject (not javax) to reflect current Eclipse platform requirements

Benefits

• For Developers: Step-by-step guidance for gradual component migration with current best practices
• For AI Agents: Structured information suitable for automated migration assistance
• For the Project: Living documentation that evolves with the codebase
• For Users: Single source of truth for migration patterns, model contributions, and best practices

Fixes #[issue_number]

Original prompt

Create Eclipse E4 Migration guide

To bring the Migration of E3 RCP to the new E4 Applicationmodel forward we neede to better document how to do things.

Even though there are some resources online:

https://devm.io/eclipse/eclipse-migration-tutorial-124527

And a lot of articles

https://eclipsesource.com/blogs/2016/01/08/migrating-from-eclipse-3-x-to-eclipse-4-e4/
https://entwickler.de/eclipse/eclipse-migration-tutorial-124527
https://www.eclipse.org/community/eclipse_newsletter/2013/february/article3.php
https://asciiware.com/eclipse-3-x-to-e4-the-migration-path/
https://github.com/fipro78/e4-cookbook-migration-guide?tab=readme-ov-file
https://vogella.com/blog/getting-your-eclipse-plug-ins-ready-for-eclipse-4/

these are often to generic and broad and often hard to find, maybe outdated and we should instead offer the current information in this repository so they can evolve with the code.

Because of this we want:

• A new Eclipse4_Migration.md in the docs folder
• Giving a short introduction, but assume the reader has already somehow started the migration and knows how to do the basic setup but now needs guidance how to grdually upgrade exsiting components
• Describing the prerequisite e.g make sure a model fragment is created, see this Wiki page: https://wiki.eclipse.org/Eclipse4/RCP/Modeled_UI/Contributing_to_the_Model if this article is not already migrated it should be migrated as Eclipse4_Model.md first so we can reference it
• Adding specific section for the topics of: Migrate a Command, Migrate a Handler, Migrate a View, Migrate a Menu
• Each topic should mention the E3 way, what is the E4 counterpart and some steps how to convert one to the other
• We want thi for the users, but also to allow using this as a promt for AI agents to help with the boilerplate of the migration

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[laeubi]

@copilot some adjustments are needed here, see review comments.

[Copilot]

@copilot some adjustments are needed here, see review comments.

All review comments addressed in commit b26036d:

• Changed javax to jakarta throughout
• Created Eclipse4_Model.md and updated references
• Added note about preserving E3 IDs when migrating
• Added important note about method injection vs field injection in handlers
• Verified character encoding issues are GitHub rendering artifacts

[laeubi]

Looks fine for a first starting point, we can improve/adjust later.

[laeubi]

Build will not test this documentation change.

[laeubi]

@vogella @opcoach @ruspl-afed please suggest enhancements to this documentation as you find sufficient in new PRs!