Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Scout/Coding Guidelines"

(Impact of API Changes)
(Replaced content with "{{ScoutPage}} Coding guidelines included in Scout/Contribution_Guidelines.")
(4 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
{{ScoutPage}}
 
{{ScoutPage}}
  
This page collects the coding guidelines for the Eclipse Scout project
+
Coding guidelines included in [[Scout/Contribution_Guidelines]].
 
+
== API Compatibility ==
+
 
+
We try to make migration to new releases as easy as possible, however to keep our code clean and simple we need to change the API in new releases.
+
 
+
=== Impact of API Changes ===
+
'''Scout Runtime:''' API Changes in the Scout Client Model, Scout Services, Utilities, etc. can have a large impact for projects using Scout, wereas changes in the UI layer (*.swt, *.swing, *.rap) are usually not relevant for projects. API changes in the Scout Runtime may require changes in the Scout SDK, Scout Demo Application, documentation, etc.
+
 
+
'''Scout SDK:''' Not many projects are extending the Scout SDK, therefore API changes are not so critical there.
+
 
+
==== What is considered breaking API change? ====
+
 
+
Adding a method to an interface in the scout model and providing a default implementation in the abstract class is not considered a breaking API change and may be ignored when writing migration notes, because (almost) all consumers of the scout code always use the abstract classes.
+
 
+
This holds for
+
* Abstract model classes: e.g. org.eclipse.scout.rt.client.ui.form.fields.stringfield.AbstractStringField
+
* UI Fields: e.g. rg.eclipse.scout.rt.ui.swing.AbstractSwingEnvironment, org.eclipse.scout.rt.ui.swing.form.fields.browserfield.internal.SwingScoutBrowserField
+
 
+
=== What is Puplic API in Scout?===
+
'''Internal Packages:''' Packages ending with .internal are not considered API. The use of such packages is possible, but discouraged. All internal packages should be exported, such that they can be used, if really needed.
+
 
+
'''UI Plugins:''' Plugins *.ui.*  are not considered API. These plugins may change more frequently.
+
 
+
=== How to change/remove/add API===
+
 
+
==== Deprecations ====
+
'''Why deprecations:'''
+
* Projects do not need to migrate everything at once, but can do some migrations later
+
* Deprecated methods can be documented. It can be described in the deprecation comment what has changed and how it can be migrated.
+
 
+
'''When do I deprecate?'''
+
* In general when API needs to be changed the old version of the API is deprecated (and still working!). Sometimes maintaining two versions of the API can be very complicated (or even impossible, e.g. with generics). In this case no deprecations are made. (If you need more than 10 minutes only to make the deprecated version still working you do not need to deprecate.)
+
* Deprecations only need to be done for releases and not for Milestone Builds.
+
** E.g. if a method name changes in Scout 3.9 M1, it is deprecated in this release and will be removed in the next open source release (Scout 4.0)
+
** E.g. if a new method is introduced in Scout 3.9 M1 and it changes in Scout 3.9 M2 it should not be deprecated, but just renamed
+
 
+
'''Please note''': If you remove a feature from Scout this may cause problems for projects using Scout. You can help by describing why this is done in the news and provide some hints for alternative solutions.
+
Ideally projects remove deprecation warnings quickly. This also means that you should provide migration notes as soon as a feature is deprecated.
+
 
+
'''How do I deprecate?:'''
+
* When you deprecate you should always try to decide when the feature is actually removed. Usually this is the next major release.
+
* A deprecation should look as follows:
+
 
+
  /**
+
  * @Deprecated: use ... instead. Will be removed in the x.y Release.
+
  */
+
  @Deprecated
+
* Remove all ocurrences of the deprecated code in Scout and demo applications. (Rare exceptions may be some testcases explicitly used to test the old functionality)
+
* Make sure there are no new warnings in the code (suppress deprecation warnings if necessary)
+
* Flag the bugzilla with migration and write migration notes
+
 
+
==== Migration Notes ====
+
 
+
==== API Freeze ====
+
M6 is API freeze, meaning that the public API should not change anymore, i.e. no more required migrations should be necessary. There may be exceptions, e.g. for high priority bugfixes.
+
 
+
M7 is feature freeze, meaning that there should also be only little additions for bugfixes.
+
 
+
 
+
Addition of a method on an interface is allowed if the default implementation is provided:
+
 
+
This holds for
+
* Abstract model classes: e.g. org.eclipse.scout.rt.client.ui.form.fields.stringfield.AbstractStringField
+
* UI Fields: e.g. rg.eclipse.scout.rt.ui.swing.AbstractSwingEnvironment, org.eclipse.scout.rt.ui.swing.form.fields.browserfield.internal.SwingScoutBrowserField
+
 
+
=== Deprectations ===
+
 
+
The scout RT API are compatible with your the previous release. Some modifications are marked with the keyword '''migration''' in bugzilla meaning that some modifications are requested.
+

Revision as of 13:21, 1 April 2014

The Scout documentation has been moved to https://eclipsescout.github.io/.

Coding guidelines included in Scout/Contribution_Guidelines.

Back to the top