------------------------------ Branches ------------------------------ Apache SIS branches The {{{./source-repository.html}source code repository}} contains a JDK6 and JDK7 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. ** <<>> The JDK7 branch is the recommended development branch for developers who can use a JDK7 environment. This branch implements the interfaces defined in the {{{http://www.geoapi.org/snapshot/index.html}GeoAPI 3.1-SNAPSHOT}} milestones and uses some JDK7-specific features like: * Syntax enhancements, mostly in exception handling (, ) but also on other aspects like . * Leveraging of new API (, , ). ** <<>> The JDK6 branch is a merge of the JDK7 branch ported to the JDK6 platform. This is the recommended development branch for developers who can not use a JDK7 environment, but still want to work closely with latest GeoAPI interfaces. The JDK6 branch implements the same GeoAPI interfaces than the JDK7 branch; the only differences (apart version number) are the modifications necessary for building and running on a JDK6 platform: * statements replaced by statements. * replaced by an explicit sequences of statements. * replaced by explicit generic types. * removed. * Imports of <<>> replaced by imports of <<>>. * Other JDK7-specific features resolved on a case-by-case basis. ** <<>> The trunk is a merge of the JDK6 branch ported to the interfaces defined by the {{{http://www.geoapi.org/3.0/index.html}GeoAPI 3.0.0}} stable release. This is the code which is built by the {{{./integration.html}continuous integration system}} and deployed on the Maven repository. The only differences (apart version number) compared to the JDK6 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. * 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 have not yet been merged; * 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. In particular, if a block merged from the JDK7 branch must be changed in the JDK6 branch because of language changes, try to replace it by a block construct using the same indentation. For example the following JDK7 construct: ------------------------------------------------- switch (string) { case "ABC": { invokeABC(); break; } case "DEF": { invokeDEF(); break; } } ------------------------------------------------- can be replaced by the code below. The outer <<<\{…\}>>> would normally not be needed and the <<>> statement would normally follow the previous <<<\}>>>, however in this example we aim to preserve the indentation of the <<>> bodies. ------------------------------------------------- { // This is a switch(String) on the JDK7 branch if (string.equals("ABC")) { invokeABC(); } else if (string.equals("DEF")) { invokeDEF(); } } ------------------------------------------------- ** 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; // Related to JDK7 import java.util.Objects; ------------------------------------------------- ** Replacement on non-existent classes When using a JDK7 class that does not exist on JDK6, define a class of the same name in a <<>> sub-package with the minimal amount of needed functionalities, provided that it can be done with reasonable effort. Otherwise just delete the JDK7-dependent code from the JDK6 branch. * Performing the merges Subversion 1.5 and later maintain a <<>> 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: * <<>> as a checkout of <<>>. * <<>> as a checkout of <<>>. However the instructions below can be adapted to different directory locations by changing the paths given in argument to the <<>> and <<>> commands. Assuming that the developer wants to merge the changes the JDK7 directory the JDK6 directory, then the following commands can be executed. Do <> specify any revision number to the <<>> command. Instead, let Subversion infers the proper revisions range from the <<>> property. ----------------- cd JDK7 svn update cd ../JDK6 svn update svn merge ../JDK7 ----------------- If Subversion reports any conflicts (flagged by the <<>> 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 <<>> will find compilation problems much faster than <<>>. 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 <<>> again). ---------------- mvn clean mvn compile mvn test-compile mvn install ---------------- After a successful build, commit: ------------------------------------------- svn commit -m "Merge from the JDK6 branch." ------------------------------------------- ** Declaring that some changes shall not be merged If a developers wants to apply some changes specific to the JDK7 platform and tells Subversion to not propagate those changes to the JDK6 branch, then the following procedure shall be applied: * Before to apply JDK7-specific changes, merge any pending changes to the JDK6 branch. * Apply the JDK7-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): ------------------------------------------- cd JDK7 svn update cd ../JDK6 svn update svn merge --record-only ../JDK7 svn commit -m "Skip JDK7-specific changes." -------------------------------------------