...
+```
Another reason for using natures is to make use of the nature lifecycle methods when your plug-in is connected to or disconnected from a project. When a nature is added to a project for the first time, the nature's configure method is called. When the nature is removed from the project, the deconfigure method is called. This is an opportunity to initialize metadata on the project and to associate additional attributes, such as builders, with the project.
diff --git a/docs/FAQ/FAQ_Why_should_I_use_the_new_progress_service.md b/docs/FAQ/FAQ_Why_should_I_use_the_new_progress_service.md
index 168dd280ff2..6f2ead01578 100644
--- a/docs/FAQ/FAQ_Why_should_I_use_the_new_progress_service.md
+++ b/docs/FAQ/FAQ_Why_should_I_use_the_new_progress_service.md
@@ -7,6 +7,7 @@ Eclipse 3.0 introduced a central new workbench _progress service_. This service
The service is used much like the SWT BusyIndicator. Simply pass an IRunnableWithProgress instance to the busyCursorWhile method. The UI will prevent further user input and report progress feedback until the runnable completes. Note that the runnable executes in a non-UI thread, so you will have to use asyncExec or syncExec to execute any code within the runnable that requires access to UI widgets:
+```java
IWorkbench wb = PlatformUI.getWorkbench();
IProgressService ps = wb.getProgressService();
ps.busyCursorWhile(new IRunnableWithProgress() {
@@ -14,6 +15,7 @@ The service is used much like the SWT BusyIndicator. Simply pass an IRunnableWit
... do some long running task
}
});
+```
This progress service was introduced to unify a number of progress-reporting mechanisms in Eclipse 2.1. JFace provides a Progress Monitor dialog, SWT provides a busy indicator, and the workbench provides a progress indicator on the status line. Each of these mechanisms has its own advantages and disadvantages. The busy cursor is the least obtrusive and works well for tasks that typically take a second or less. The Progress dialog provides much more information and allows the user to cancel but is visually distracting, especially on short tasks as it pops up over the user's work. The status line progress monitor is a bit less obtrusive but doesn't give an obvious indication that the UI is not accepting further input, and the space for presenting progress indication is very constrained. The new progress service tries to achieve a balance by automatically adapting between a busy cursor and a dialog, depending on the situation.
diff --git a/docs/Javadoc.md b/docs/Javadoc.md
index 2e7268bed88..23e8cdb6944 100644
--- a/docs/Javadoc.md
+++ b/docs/Javadoc.md
@@ -17,7 +17,9 @@ All HTML tags must be explicitly terminated
All HTML tags appearing in Javadoc comments must be explicitly terminated, even the ones that are considered optional in older versions of HTML such as
+```html
...
+```
Various internal tools that post-process the extracted HTML documentation into other forms (e.g., Windows help file) need these tags.
diff --git a/docs/Progress_Reporting.md b/docs/Progress_Reporting.md
index 041b8977743..e25241ec6fd 100644
--- a/docs/Progress_Reporting.md
+++ b/docs/Progress_Reporting.md
@@ -12,11 +12,13 @@ I recently got to investigate issues in p2 why the progress bar did not move whi
The problem is how to handle a case where you need to do something like this:
+```java
for (int i = 0; i < candidates.length; i++) {
if (loadCandidate1(i)) {
break;
}
}
+```
Where a call to `loadCandidate(int)` is potentially a long running task. The first loaded candidate means we are done.
@@ -25,7 +27,7 @@ Antipattern
Here is an implementation of the above example using the antipattern - i.e. "don't do this":
-
+```java
public void antiPattern(IProgressMonitor monitor) {
SubMonitor sub = SubMonitor.convert(monitor, candidates.length);
for (int i = 0; i < candidates.length; i++) {
@@ -48,6 +50,7 @@ Here is an implementation of the above example using the antipattern - i.e. "don
}
return false;
}
+```
Well, what is wrong with this, you may ask...Well, the length of the progress bar will be divided into as many slots as there are candidates, and if the first candidate succeeds and uses its 1000 ticks, and the remaining candidates are never considered, we will end up reporting the 1000 ticks on a fraction of the overall progress bar. This means that for 10 candidates, you will see the progress-bar slowly go to about 10% of the overall length, to suddenly jump to 100%.
@@ -56,6 +59,7 @@ Good pattern
Here is the good pattern that makes use of the full progress bar:
+```java
public void goodPattern(IProgressMonitor monitor) {
SubMonitor sub = SubMonitor.convert(monitor, 1000);
for (int i = 0; i < candidates.length; i++) {
@@ -82,6 +86,7 @@ Here is the good pattern that makes use of the full progress bar:
}
return false;
}
+```
Notice how [`setWorkRemaining(int)`](http://help.eclipse.org/stable/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/core/runtime/SubMonitor.html#setWorkRemaining(int)) is called each time in the loop. This reallocates the remaining ticks, but there is no need to compute how many that actually remains, the child allocation of 1000 ticks will always give the child 1000 ticks to report, even if there were not enough ticks left in the parent. All the scaling is performed by the SubMonitor, so you don’t have to worry about it.
@@ -92,6 +97,7 @@ Good pattern - regular loop
Here is the good pattern for a regular loop where each iteration does consume ticks.
+```java
public void goodLoopPattern(IProgressMonitor monitor) {
SubMonitor sub = SubMonitor.convert(monitor, candidates.length*100);
for (int i = 0; i < candidates.length; i++) {
@@ -116,6 +122,7 @@ Here is the good pattern for a regular loop where each iteration does consume ti
}
return false;
}
+```
Here I simply use SubMonitor’s [`newChild(int)`](http://help.eclipse.org/stable/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/core/runtime/SubMonitor.html#newChild(int)), this works without calling “done” because the next call to newChild (or “done” for that matter) will consume the ticks allocated for the child.
diff --git a/docs/Provisional_API_Guidelines.md b/docs/Provisional_API_Guidelines.md
index 51f63779797..d8b645059ca 100644
--- a/docs/Provisional_API_Guidelines.md
+++ b/docs/Provisional_API_Guidelines.md
@@ -7,10 +7,10 @@ Overview
Eclipse APIs undergo a development process, passing through many phases from initial forms to real APIs with guarantees of long term support.
It is important that API clients understand the state of the APIs in any given build of Eclipse.
-This document sets out API guidelines for the Eclipse Project committers on how to indicate APIs that are still under development and subject to change.
+This document sets out API guidelines for the Eclipse Project committers on how to indicate APIs that are still under development and subject to change.
These guidelines are also useful for API clients who want to know about the state of a given API they are using.
-The development cycle for each major and minor Eclipse project release has a release designated as the API freeze.
+The development cycle for each major and minor Eclipse project release has a release designated as the API freeze.
The rules for development and treatment of APIs are different for the periods before and after this point, so this document outlines guidelines for both phases of the development cycle.
Definition of terms used in this document:
@@ -18,7 +18,7 @@ Definition of terms used in this document:
**API package**
A package must be exported via the MANIFEST.MF to be considered API.
-However, any package that does contain the segment "internal" and which has not set the x-internal or the x-friends directive in the MANIFEST.MF is not API.
+However, any package that does contain the segment "internal" and which has not set the x-internal or the x-friends directive in the MANIFEST.MF is not API.
See [Naming Conventions](Naming_Conventions.md) for details)
**Internal API**
@@ -31,15 +31,15 @@ A public Java class or interface in an API package, or a public or protected met
**Provisional API**
-An API element that has not existed in any release of the Eclipse project.
-All provisional API is subject to arbitrary change or removal without any notice.
-This document refers to all non-final APIs as provisional APIs.
+An API element that has not existed in any release of the Eclipse project.
+All provisional API is subject to arbitrary change or removal without any notice.
+This document refers to all non-final APIs as provisional APIs.
Provisional API has set the x-internal or the x-friends directive for the package in the MANIFEST.MF
Before the API freeze
---------------------
-Prior to the API freeze, any API element that did not exist in the previous release is provisional by definition. This is true regardless of the package name, bundle manifest, or javadoc of the types involved.
+Prior to the API freeze, any API element that did not exist in the previous release is provisional by definition. This is true regardless of the package name, bundle manifest, or javadoc of the types involved.
However, the conventions below should be used to indicate where API is provisional.
### Package naming
@@ -50,13 +50,13 @@ New code that are not intended to become API in time for one of the upcoming rel
### Bundle manifest
-All API packages should be exported unconditionally by the bundle manifest.
+All API packages should be exported unconditionally by the bundle manifest.
If internal packages are exported, they should be marked via the x-internal or the x-friends directive in the MANIFEST.MF.
### Javadoc
-The primary indicator of provisional API is the @since tag, indicating that it was introduced during the current development period.
-For example, during development leading up to the 3.4 release of Eclipse, a tag of @since 3.4 designates provisional API.
+The primary indicator of provisional API is the @since tag, indicating that it was introduced during the current development period.
+For example, during development leading up to the 3.4 release of Eclipse, a tag of @since 3.4 designates provisional API.
If the API is particularly volatile, experimental, or at risk of removal, a further comment in the javadoc can be used to clarify the state of the API:
*
@@ -64,53 +64,53 @@ If the API is particularly volatile, experimental, or at risk of removal, a furt
* part of a work in progress. There is no guarantee that this API will
* work or that it will remain the same. Please do not use this API without
* consulting with the team.
- *
`
+ * `
+
-
Though not required, inserting this paragraph in your class or interface javadoc makes the state of the API very clear to potential clients. By indicating the name of the responsible team in the comment, you allow for interaction with prospective clients. If a prospective API client contacts the developer of the provisional API, they can agree on a certain level of stability and advanced warning before changes are made in the API. Also note that while you don't need to use the exact template described above, a consistent template does make it easier to find and remove these comments when finalizing the API.
After the API freeze
--------------------
-From the perspective of code maintenance, there is really no such thing as "provisional API".
-Either it is complete and committed platform API, or it is internal code.
-API that is new in the current release cycle is still subject to change, but changes after this point are rare and require approval from the Eclipse project [PMC](https://eclipse.dev/eclipse/team-leaders.php).
+From the perspective of code maintenance, there is really no such thing as "provisional API".
+Either it is complete and committed platform API, or it is internal code.
+API that is new in the current release cycle is still subject to change, but changes after this point are rare and require approval from the Eclipse project [PMC](https://eclipse.dev/eclipse/team-leaders.php).
-Note that there are no guarantees about the existence or shape of internal code, even if the package name or comments suggest that it may become API in the next release.
-In particular, the API contract (binary upwards compatibility) does not apply.
-Clients who think they must use internal code may do so at their own risk, or with slightly less risk if they can reach an agreement with the team that developed the internal code.
+Note that there are no guarantees about the existence or shape of internal code, even if the package name or comments suggest that it may become API in the next release.
+In particular, the API contract (binary upwards compatibility) does not apply.
+Clients who think they must use internal code may do so at their own risk, or with slightly less risk if they can reach an agreement with the team that developed the internal code.
Note also that in such cases, the required versions for plug-in dependencies need to be specified with great care.
### Package naming
-All internal code that is not intended to become API at some point must be in a package whose name contains the segment "internal".
+All internal code that is not intended to become API at some point must be in a package whose name contains the segment "internal".
Internal code that is planned to become API in a future release must be marked as internal via the x-internal or x-friends directive in the MANIFEST.MF.
### Bundle manifest
-All API packages should be exported unconditionally by the bundle manifest.
+All API packages should be exported unconditionally by the bundle manifest.
Internal packages may also exported, they must be marked as x-internal in this case.
### Javadoc
-No special javadoc treatment for internal code is needed.
-Note that @since tags also have little significance for internal code at this point.
-If internal code is added in the 3.4 development period, but promoted to real API in the 3.5 development period, the correct tag for that API will be @since 3.5.
+No special javadoc treatment for internal code is needed.
+Note that @since tags also have little significance for internal code at this point.
+If internal code is added in the 3.4 development period, but promoted to real API in the 3.5 development period, the correct tag for that API will be @since 3.5.
The experimental javadoc paragraph can be left in the class or interface comment, but is not required.
Changing provisional APIs
-------------------------
-Technically, a provisional API can change arbitrarily or be removed at any time without notice.
-Clients in the greater community who are consuming Eclipse milestone and integration builds cannot make any assumptions about the state of any provisional API between any two non-release builds.
-However, committers have a shared responsibility to ensure that integration builds are not broken due to changes in provisional APIs.
-Known clients of the provisional API within the SDK should be given fair warning and a chance to react before breaking changes are made.
+Technically, a provisional API can change arbitrarily or be removed at any time without notice.
+Clients in the greater community who are consuming Eclipse milestone and integration builds cannot make any assumptions about the state of any provisional API between any two non-release builds.
+However, committers have a shared responsibility to ensure that integration builds are not broken due to changes in provisional APIs.
+Known clients of the provisional API within the SDK should be given fair warning and a chance to react before breaking changes are made.
As a courtesy to the community, and to minimize the risk of build failures, it is useful to deprecate provisional APIs slated for change or removal in at least one integration build before making the change. Although not required, adding such a temporary tag can ease the transition for early adopters of the API:
- * @deprecated This API will be removed in I20380119. Method {@link #blort()} should be used instead.`
+ * @deprecated This API will be removed in I20380119. Method {@link #blort()} should be used instead.`
+
-
Note that there are no restrictions on changing internal code before or after the API freeze. Since all such code is in internal packages after this point, it can change arbitrarily without notice up to and including the final build of the release.
diff --git a/docs/Status_Handling_Best_Practices.md b/docs/Status_Handling_Best_Practices.md
index 679885283d4..47b831368c4 100644
--- a/docs/Status_Handling_Best_Practices.md
+++ b/docs/Status_Handling_Best_Practices.md
@@ -10,10 +10,10 @@ Introduction
In software engineering serviceability is also known as supportability, and refers to the ability to debug or perform root cause analysis in pursuit of solving a problem with a product.
Serviceability includes the logging of state and the notification of the user.
-Eclipse provides a framework to manage the Log file as well as Dialog to notify the user.
+Eclipse provides a framework to manage the Log file as well as Dialog to notify the user.
This framework allows provider to plug-in their diagnosis tools, providing extra value to the user.
-This paper explains the best practices of using the IStatus class.
+This paper explains the best practices of using the IStatus class.
The second part explains to plug-in provider how to exploit the new ‘StatusHandler’ model, allowing them to contribute to the user interface as well as managing the IStatus we are about to show or log.
Before we investigate IStatus, we need to agree on a couple basic principle about logging and error message rendering.
@@ -25,14 +25,14 @@ Messages
A message is the principal information the user will see in the log or in the User Interface. A message that is logged is supposed to be user consumable and thus follow the same readability and globalization rules as a String rendered in a menu.
-
+
Message content
---------------
There are tons of information on how to create a usable message. We rely on your Software Engineering experience to avoid messages like: ‘internal error, please see log’.
-
+
Provide additional information in your message
----------------------------------------------
@@ -42,7 +42,7 @@ We recommend you provide two other pieces of information when you create a messa
1. An explanation of the message. This is a String that will provide more information to the user than a one line message. The explanation should not be too technical, yet provide more value than the message text itself. Once again, information is available on the web.
2. A recommendation of the message. This is a String that will tell the user what he/she should do. When you write this part, put yourself in the shoes of the user and answer the following question: “ok, now what do I do ?”
-
+
Attempt to use a unique identifier
----------------------------------
@@ -52,7 +52,7 @@ Unique identifier could be an int or a String that uniquely tag the message. The
1. It is easier to search a knowledge base with a unique int than the full text of the message.
2. Because messages are translated, a user in a foreign country may send your support team a translated message. If you do not have a unique identifier, it will be difficult for your team to translate it back into the original language.
-
+
Developing messages in eclipse: using the NLS.bind method
---------------------------------------------------------
@@ -103,29 +103,31 @@ Most of the framework related to Logging and Error rendering uses an IStatus:
* ILog.log(IStatus status)
* IProgressMonitorWithBlocking.setBlocked(IStatus reason)
* ErrorDialog.openError(Shell parent, String dialogTitle, String message, IStatus status)
-
-
+
+
Calling the Status API
----------------------
-You should investigate the Status and MultiStatus classes.
+You should investigate the Status and MultiStatus classes.
We recommend you use the following constructor:
+```java
public Status(int severity, String pluginId, int code, String message, Throwable exception)
-
+```
Implementing your own Status
----------------------------
You should consider the following when creating an IStatus instance.
-1. Try to create a subclass of IStatus that will carry your specific payload.
-An Example in Eclipse 3.3 is the class CVSStatus.
+1. Try to create a subclass of IStatus that will carry your specific payload.
+An Example in Eclipse 3.3 is the class CVSStatus.
The class carries information that diagnostic tool can use to validate CVS.
2. Do not use IStatus.ERROR as a code. Try to use your own code. As an example, look at the Class CVSSTatus.
+```java
public class CVSStatus extends TeamStatus {
/*** Status codes ***/
@@ -140,6 +142,7 @@ The class carries information that diagnostic tool can use to validate CVS.
super(severity, CVSProviderPlugin.ID, code, message, t,null);
this.cvsLocation = cvsLocation;
}
+```
The Eclipse 3.3 Status handler framework
========================================
@@ -164,6 +167,7 @@ Calling the new framework is straight forward. Once your IStatus is created, you
Remember the Handler has the last decision about showing and logging. Consider the previous information as a hint to the handler, but do not rely on them for your execution.
+```java
public void run(IAction action) {
// Throw an error to be handled
File aConfigurationFile = obtainConfigurationFileFor(authenticatedUser);
@@ -183,8 +187,9 @@ Remember the Handler has the last decision about showing and logging. Consider t
if (aStream!=null){
try {aStream.close();} catch (Exception e){};
}
- }
+ }
}
+```
Developing a StatusHandler
==========================
@@ -196,22 +201,23 @@ A StatusHandler is the counterpart of StatusManager. As a developer, you will ca
Implementing the handle method
------------------------------
+```java
public void handle(StatusAdapter statusAdapter, int style) {
// Retrieve IStatus and message
- IStatus oldStatus = statusAdapter.getStatus();
+ IStatus oldStatus = statusAdapter.getStatus();
// Verify we do not have a CompanyStatusWithID
if (!(oldStatus instanceof CompanyStatusWithID)){
String message = oldStatus.getMessage();
//All our ID start with DYNA
- if (null!=message && message.startsWith("DYNA")){
+ if (null!=message && message.startsWith("DYNA")){
//Remove any unique identifier to not show it to the user
int lengthOfUniqueId = message.indexOf(' ');
- String uniqueID = message.substring(0,lengthOfUniqueId);
+ String uniqueID = message.substring(0,lengthOfUniqueId);
message = message.substring(lengthOfUniqueId);
message = message + getExplanation(oldStatus); // Retrieve the explanation for this status
@@ -228,6 +234,7 @@ Implementing the handle method
super.handle(statusAdapter, style);
}
+```
Developing an ErrorSupportProvider
==================================
@@ -240,9 +247,9 @@ To Register your SupportArea, you must call the following code
Policy.setErrorSupportProvider();
Policy.setErrorSupportProvider();
-
-
+
+
We recommend you do it in the Activator class of your bundle, in the start method. Of course you can change it later, for instance in your handle method. In that case, there is no contract that the ErrorSupportProvider you set will be the one receiving the IStatus your are processing.
@@ -251,6 +258,7 @@ Implementing the createSupportArea method
Implement the createSupportArea method, returning the control you want to show the user.
+```java
public Control createSupportArea(Composite parent, IStatus status) {
parent.addDisposeListener(this); // get notified so we can clean our SWT widgets
@@ -262,15 +270,18 @@ Implement the createSupportArea method, returning the control you want to show t
toolkit.getColors().initializeSectionToolBarColors();
...
}
+```
Here is a simple example that will open a web page.
+```java
public Control createSupportArea(Composite parent, IStatus status) {
viewer = new Browser(parent, SWT.NONE);
viewer.setLayoutData(new GridData(SWT.FILL,SWT.FILL,true,true));
viewer.setUrl();
return viewer;
}
+```
We highly recommend you implement an IDisposeListener to clean up after yourself, when the ErrorDialog is closed.
diff --git a/docs/VersionNumbering.md b/docs/VersionNumbering.md
index 1bdeb0e6b6a..44751fa4c2d 100644
--- a/docs/VersionNumbering.md
+++ b/docs/VersionNumbering.md
@@ -18,15 +18,15 @@ Each segment captures a different intent:
### When to change the major segment
-The major segment number must be increased when a plug-in makes breaking changes to its API.
-When the major segment is changed the minor and service segments are reset to 0.
+The major segment number must be increased when a plug-in makes breaking changes to its API.
+When the major segment is changed the minor and service segments are reset to 0.
See [Evolving Java-based APIs](Evolving-Java-based-APIs.md) for details on what constitutes a breaking change.
**Example**: From the version 2.2.7, an incompatible change would lead to 3.0.0. By definition, such changes should not be made when working in a maintenance stream.
### When to change the minor segment
-The minor segment number must be incremented when a plug-in changes in an "externally visible" way.
+The minor segment number must be incremented when a plug-in changes in an "externally visible" way.
Examples of externally visible changes include [binary compatible API changes](Evolving-Java-based-APIs-2.md) or an increased minimum Java version via the Bundle-RequiredExecutionEnvironment header in the MANIFEST.MF, significant performance changes, major code rework, adding a new extension point, changing files with a somewhat unclear API status (e.g. changing icons from gif to png), etc. Another way to know when this version number should be changed is by exclusion: it should indicate changes that are neither bug fixes (indicated by the service segment) nor breaking API changes (indicated by the major segment). When the minor segment is changed, the service segment is reset to 0.
**Example**: From the version 2.2.7, a minor change would lead to 2.3.0.
@@ -45,17 +45,17 @@ This example shows how the version of a plug-in reacts to changes (indicated in
First development stream
- 1.0.0
-
+
Second development stream
- 1.0.100 (indicates a bug fix)
- 1.1.0 (a new API has been introduced)
The plug-in ships as 1.1.0
-
+
Third development stream
- 1.1.100 (indicates a bug fix)
- 2.0.0 (indicates a breaking change)
The plug-in ships as 2.0.0
-
+
Maintenance stream after 1.1.0
- 1.1.1
The plug-in ships as 1.1.1
@@ -127,16 +127,17 @@ Exported packages being used as service APIs must have a version number. The gui
In the Javadoc, @since tags are used to indicate the version of a **plug-in** in which a specific API has been added. Because Javadoc describes API, only the first two segment of the plug-in version number should be used. This represents a change from the previous practice where @since indicated the development stream. In addition to using the plug-in version, we recommend to prefix the version number by the plug-in id. This allows tracking of APIs moving from one plug-in to another (this can happen when a plug-in is split into multiple plug-ins but the package names are kept). **Example**: In the 3.2 development stream, the API of the new plug-in org.eclipse.core.filesystem should be tagged as follows:
-
+```java
/**
* This class is the main entry point for clients of the Eclipse file system API. This
* class has factory methods for obtaining instances of file systems and file
* stores, and provides constants for option values and error codes.
- *
+ *
* @noextend This class is not intended to be subclassed by clients.
* @noinstantiate This class is not intended to be instantiated by clients.
* @since org.eclipse.core.filesystem 1.0
*/
+```
Versioning features
-------------------
@@ -153,8 +154,8 @@ A branding plug-in should keep its version in sync with its feature.
### To require features or to require bundles
-A feature can express its external dependencies as required features, required plug-ins, or a combination of the two.
-How dependencies are expressed has consequences on the install-time behavior of your feature, so it is important to understand the different approaches.
+A feature can express its external dependencies as required features, required plug-ins, or a combination of the two.
+How dependencies are expressed has consequences on the install-time behavior of your feature, so it is important to understand the different approaches.
These approaches are described below along with a discussion of their effect.
Feature dependencies do not have to express dependencies that are already expressed at the plug-in level.
Such duplication or further refinement of dependency information between features and plug-ins may unnecessarily restrict the ability to install the feature. With the classic Eclipse Update Manager that was the default install/update technology prior to Eclipse 3.4, dependency information was required at the feature level because the provisioning technology only reasoned at the level of features.
@@ -173,21 +174,21 @@ Expressing dependencies directly at the plug-in level has the benefit of isolati
contains plugins:
org.eclipse.draw2d 3.1.0
org.eclipse.gef 3.1.0
-
+
Case 2: It is better to express this as:
contains plugins:
org.eclipse.draw2d 3.1.0
- org.eclipse.gef 3.1.0
+ org.eclipse.gef 3.1.0
requires plugins:
org.eclipse.core.runtime 3.1.0 match="compatible"
org.eclipse.ui.views 3.1.0 match="compatible"
org.eclipse.ui.workbench 3.1.0 match="compatible"
org.eclipse.jface 3.1.0 match="compatible"
org.eclipse.swt 3.1.0 match="compatible"
-
-
-
+
+
+
In case 1, if the version of the org.eclipse.platform feature changes to 4.0.0 (because org.eclipse.core.resources changes its major version number), org.eclipse.gef is required to deliver a new version of its features. In case 2, such changes are transparent to the author of GEF.
@@ -198,7 +199,7 @@ In case 1, if the version of the org.eclipse.platform feature changes to 4.0.0 (
#### Require features
Use required features when you want another entire feature to be present when your feature is installed. This typically results in a user-level awareness of the required feature, rather than a hidden implementation detail of your feature.
-For example, users installing Java EE tools from the [Web Tools Platform](http://www.eclipse.org/webtools/) project also require [Java development tools](https://github.com/eclipse-jdt).
+For example, users installing Java EE tools from the [Web Tools Platform](http://www.eclipse.org/webtools/) project also require [Java development tools](https://github.com/eclipse-jdt).
This is not just because their plug-ins depend on plug-ins in JDT, but because users of the Java EE tools really expect the full JDT to be there, including documentation, help content, and possibly source. In this case the dependency should be expressed at the feature level to ensure the entire required feature is installed. Feature-level dependencies are also required if you are targeting a platform using the classic Eclipse Update Manager, which operated purely at the level of feature dependencies.
### Feature includes