Apache SIS branches

The source code repository contains JDK7 and JDK8 branches together with the trunk. The Apache SIS releases are created from the code on the trunk only. However the actual development often occur on a branch before to be merged to the trunk. Those branches exist in order to experiment early the new technologies — since it may impact the library design — while keeping the releases compatible with more common environments.

This page lists the Apache SIS development branches, provides some coding recommendations for making merges easier, then provides the steps to follow for performing the merges.

The development branches

Developers are encouraged to select the first branch listed below, in that order, which meet their needs.

branches/JDK8

The JDK8 branch is the recommended development branch for developers who can use a JDK8 environment. This branch implements the interfaces defined in the GeoAPI snapshot milestones and uses some JDK8 or JDK7-specific features like:

  • Syntax enhancements, mostly in exception handling (try-with-resources, multi-catches) but also on other aspects like diamond operator.
  • Leveraging of new API (suppressed exceptions, file systems, fork join).
  • Functional interfaces and lambda expressions.

branches/JDK7

The JDK7 branch is a merge of the JDK8 branch ported to the JDK7 platform. The JDK7 branch implements the same GeoAPI interfaces than the JDK8 branch; the only differences (apart version number) are the modifications necessary for building and running on a JDK7 platform:

  • Lambda expressions replaced by anonymous classes.
  • New methods on collection interfaces replaced by calls to static methods.
  • java.util.function and java.time API replaced by internal placeholder classes.

Behavioral differences

The JDK7 branch should behaves in a way close to identical to the JDK8 branch, with possible variations in the following aspects:

  • Usage of java.time.format.DateTimeFormatter for parsing and formatting ISO 8601 dates are simulated by usage of java.text.SimpleDateFormat. Those two formatters may not have the same tolerance to inputs that deviate from the standard.

trunk

The trunk is a merge of the JDK7 branch ported to the interfaces defined by the GeoAPI stable release. This is the code which is built by the continuous integration system and deployed on the Maven repository. The main differences (apart version number) compared to the JDK7 branch are the modifications necessary for implementing an older version of the GeoAPI interfaces:

  • Usages of non-existent GeoAPI interfaces are replaced by direct usages of the corresponding Apache SIS implementation.

  • When a new revision of a standard is available, the trunk still uses the old version since the new revision is not available in GeoAPI 3.0. Sometime it results in usage of methods that are deprecated on the SIS development branches.

For security reasons and for avoiding misleading information, the following functionalities are disabled on trunk (but are still enabled on branches as experimental features). In particular the Supervisor.ENABLED flag controls whether the MBeans documented in the org.apache.sis.console package are enabled or not.

  • In core/sis-utility/src/main/java/org/apache/sis/internal/system/Supervisor.java, the ENABLED flag is set to false.
  • In core/sis-utility/src/main/java/org/apache/sis/internal/util/TemporalUtilities.java, the REPORT_MISSING_MODULE flag is set to false.

Above flag values may change in future SIS releases.

Behavioral differences

Because of changes between GeoAPI 3.0 and GeoAPI 4.0-SNAPSHOT, the following aspects need special care:

  • If op is an instance of PassThroughOperation, then the if (op instanceof SingleOperation) expression evaluates to true on trunk but to false on SIS development branches.

Coding recommendations

The following recommendations aim to make the merges easier by reducing the extend of potential conflicts.

Formatting

Refrain from doing massive code reformatting unless:

  • the modified files do not yet exist on the other branches;
  • or the modified lines are known to be identical on all active branches (merges work well in such cases);
  • or the committer is willing to resolve the merge conflicts.

Import statements

Isolate at the end of the imports section any import statements that are specific to a platform. This separation allows any branch to re-arrange the common import statements without generating conflicts with the platform-dependent import statements. Example:

import java.io.File;
import java.util.List;
import org.apache.sis.util.ArgumentChecks;

// Branch-specific imports
import java.util.stream.Stream;

Substitution for non-existent classes

When using a JDK8 class that does not exist on JDK7, define a class of the same name in a org.apache.sis.internal sub-package with the minimal amount of needed functionalities, provided that it can be done with reasonable effort. Otherwise just delete the JDK8-dependent code from the JDK7 branch.

Performing the merges

Subversion 1.5 and later maintain a svn:mergeinfo property which make merge operations much easier. In order to get those merge information properly maintained, no merge operation shall be performed with older Subversion tools.

Merging changes between two branches

The branches and trunk checkout directories can be located anywhere on the developer machine. The following example assumes that the current directory contains the following sub-directories:

  • JDK7 as a checkout of http://svn.apache.org/repos/asf/sis/branches/JDK7.
  • JDK8 as a checkout of http://svn.apache.org/repos/asf/sis/branches/JDK8.

However the instructions below can be adapted to different directory locations by changing the paths given in argument to the cd and svn merge commands.

Assuming that the developer wants to merge the changes from the JDK8 directory to the JDK7 directory, then the following commands can be executed. Do not specify any revision number to the svn merge command. Instead, let Subversion infers the proper revisions range from the svn:mergeinfo property.

cd JDK8
svn update
cd ../JDK7
svn update
svn merge ../JDK8

If Subversion reports any conflicts (flagged by the C letter before the file names), then edit the conflicted files in any IDE and mark them as resolved:

svn resolved path/to/the/resolved/file

Clean the workspace and test the build. We suggest to execute the Maven commands in the following order, since mvn compile will find compilation problems much faster than mvn install. If any of those commands fail, edit the files at cause and re-try from the command that failed (there is usually no need to run mvn clean again).

mvn clean
mvn compile
mvn test-compile
mvn install

After a successful build, commit:

svn commit --message "Merge from the JDK8 branch."

Declaring that some changes shall not be merged

If a developers wants to apply some changes specific to the JDK8 platform and tells Subversion to not propagate those changes to the JDK7 branch, then the following procedure shall be applied:

  • Before to apply JDK8-specific changes, merge any pending changes to the JDK7 branch.
  • Apply the JDK8-specific changes and commit.
  • Run the following commands (edit the path arguments if the directory layout is different than the example from the previous section):

Commands:

cd JDK8
svn update
cd ../JDK7
svn update
svn merge --record-only ../JDK8
svn commit --message "Skip JDK8-specific changes."