Difference between revisions of "Scout/Contribution Guidelines"
(→Git and Gerrit)
|Line 7:||Line 7:|
Learn how to contribute step by step: [[Scout/
Learn how to contribute step by step: [[Scout/]]
== Why do we use Git and Gerrit? ==
== Why do we use Git and Gerrit? ==
Revision as of 10:19, 15 August 2014
|Download • Git|
|Forums • Blog • Twitter|
This page is for scout committers and contributers.
- 1 Git and Gerrit
- 2 API Compatibility
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/).
|develop||Contains the very latest sources. This branch is used for building the nightly version and contains the development of the newest features that usually will be available to the next stable release.||develop: development for 4.0.0 release (Luna)||http://download.eclipse.org/scout/nightly|
|master||Contains the sources of the latest stable release.||master: stable branch for 3.9.2 (Kepler) release||http://download.eclipse.org/scout/releases|
|x.y (e.g. 3.8)||Version branches containing the sources for the corresponding Scout version. These branches exist as long as the corresponding version of Scout is still supported and releases containing bugfixes are shipped.||3.8: stable branch for 3.8 (Juno) release||http://download.eclipse.org/scout/releases/x.y|
|releases/<release_name>||Contains the development for the corresponding releases. So e.g. a release branch named 4.0.x contains the fixes for the Luna release. These branches will be merged into the origin branch (the branch from where the release branch has been created) and develop branch as soon as the corresponding release is shipped. Afterwards the branch is deleted and the merge into the origin branch is tagged.||releases/3.10.x: bugfix branch for 3.10 release||http://download.eclipse.org/scout/releases/x.y/x.y.z|
|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 develop branch and the feature branch is deleted. If multiple developers are working on the same feature, the username of the main responsible is used.||-||-|
|hotfix/<hotfix_name>||Contains branches in which hotfixes for a release are developed. After the hotfix development is complete, the hotfix branch is merged into the develop and the origin branch (the branch from where the hotfix branch has been created). Then the origin branch is tagged and the hotfix branch is deleted.||-||-|
Git Repositories and current Branches
- 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.
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 (*.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.
This section lists some conventions to follow when contributing Scout code.
- When a member of type collection (Lists, Sets, Maps, etc.) is returned from a method, a copy should be created. This can e.g. be done by using the CollectionUtility class. Collections.unmodifiableList() and Collection.emptyList() should not be used. All lists that are returned from a method are therefore mutable and ready to directly be used.
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 Plugins: Plugins *.ui.* are not considered API. These plugins 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
- 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
Bugzillas with API modifications have to be marked with the whiteboard keyword migration.
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.