Scout/Contribution Guidelines

The Scout documentation has been moved to https://eclipsescout.github.io/. This page is for scout committers and contributors.

Git and Gerrit

Learn how to contribute step by step: Scout/Contribution#Source_Code_Contribution

Why do we use Git and Gerrit?

These are the advantages that are relevant to us:

• Easy Local Branching: Creating and using multiple local branches for different features is easy and fast. We can work on more than one feature or bugfix in parallel, if necessary. We can do experiments without any worries to mess up anything important.
• Fast Switching: With Git it is faster to switch between different versions. This is useful to analyze different behaviour between versions and find bugs.
• External Contributions: We can handle contributions from non-committers faster and more easily. Up until now there where only a few contributions from non-committers pushed to gerrit.
• Stability: Git and Gerrit helps to make continuous integration easier, because only contributions that build sucessfully (and unit tests pass) are contributed into the main repository. This makes our environment more stable.
• Integration with Maven/Tycho Build: Git works well with maven/tycho. E.g. we use the git timestamp as a qualifier for the plugin artefacts. Snapshot binaries are only new for new changes.

Git Branching Policy

The following table describes the branching policy used for the Eclipse Scout Git Repositories (http://git.eclipse.org/c/scout/).

Branch	Usage	P2
releases/<release_name>	Contains the source code for the corresponding releases. These branches are considered unstable as long as the release is in development, even though we try hard to only push stable features. After the release is done, bugfixes for the corresponding releases are pushed to these branches as well. This makes it very easy to find the source code for every Scout release.	For Scout SDK and for Scout RT <= 5.0: http://download.eclipse.org/scout/releases/x.y/x.y.z Scout RT >= 5.1: no P2-Repos anymore
features/<developer_user_name>/<feature>	Contains developer private feature branches that contain the developments of new features. As soon as the feature development is complete, this branch is merged into the release branch and the feature branch is deleted. If multiple developers are working on the same feature, the username of the main responsible is used.	-

Git Repositories and current Branches

Please see http://wiki.eclipse.org/Scout/Contribution#Getting_the_Scout_Sources.

Known Issues

• It happened before that our company IP was blocked for ssh connection to git.eclipse.org/dev.eclipse.org. -> Mail or create a bug to webmaster. Remember that ssh is not necessary for fetch.

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, whereas changes in the UI layer 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 Public API in Scout?

Internal Packages: Packages containing .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 Plugin: Plugin org.eclipse.scout.rt.ui.html us not considered API. This plugin may change more frequently.

Breaking API changes

Every change on classes that are not considered public API is not considered breaking and can be done also after the API freeze. Migration notes might be helpful (or not).

Adding a method to an interface: 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. org.eclipse.scout.rt.ui.swing.AbstractSwingEnvironment, org.eclipse.scout.rt.ui.swing.form.fields.browserfield.internal.SwingScoutBrowserField

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 e.g. 10 minutes only to make the deprecated version still working you do not need to deprecate.)
• Deprecations only need to be done across releases and not between 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

If your contribution contains API modifications or change of behavior that the developer needs to know, you have to describe the steps to take when migrating to the next version containing your contribution in the Migration Guide (e.g. https://eclipsescout.github.io/8.0/migration-guide.html for Scout 8.0).

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 after M7.