Author: desruisseaux
Date: Sat Oct 6 09:32:41 2012
New Revision: 1394974
URL: http://svn.apache.org/viewvc?rev=1394974&view=rev
Log:
Added documentation about branches.
Added:
sis/branches/JDK7/src/site/apt/branches.apt (with props)
Modified:
sis/branches/JDK7/src/site/apt/develop.apt
sis/branches/JDK7/src/site/apt/index.apt
Added: sis/branches/JDK7/src/site/apt/branches.apt
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/src/site/apt/branches.apt?rev=1394974&view=auto
==============================================================================
--- sis/branches/JDK7/src/site/apt/branches.apt (added)
+++ sis/branches/JDK7/src/site/apt/branches.apt Sat Oct 6 09:32:41 2012
@@ -0,0 +1,232 @@
+ ------------------------------
+ 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.
+
+
+
+** <<<branches/JDK7>>>
+
+ 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 (<try-with-resources>,
<multi-catches>)
+ but also on other aspects like <diamond operator>.
+
+ * Leveraging of new API (<suppressed exceptions>, <file systems>, <fork
join>).
+
+
+
+** <<<branches/JDK6>>>
+
+ 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:
+
+ * <Try-with-resources> statements replaced by <try-finally> statements.
+
+ * <Multi-catches> replaced by an explicit sequences of <catch> statements.
+
+ * <Diamond operators> replaced by explicit generic types.
+
+ * <Suppressed exceptions> removed.
+
+ * Imports of <<<java.util.Objects>>> replaced by imports of
<<<org.apache.sis.internal.util.Objects>>>.
+
+ * Other JDK7-specific features resolved on a case-by-case basis.
+
+
+
+** <<<trunk>>>
+
+ 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 <<<else>>> statement would normally follow the previous <<<\}>>>,
however in
+ this example we aim to preserve the indentation of the <<<case>>> 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
+ <<<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 JDK7-dependent
+ code from the JDK6 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:
+
+ * <<<JDK6>>> as a checkout of
<<<http://svn.apache.org/repos/asf/sis/branches/JDK6>>>.
+
+ * <<<JDK7>>> as a checkout of
<<<http://svn.apache.org/repos/asf/sis/branches/JDK7>>>.
+
+ 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 JDK7
directory
+ <to> the JDK6 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 JDK7
+svn update
+cd ../JDK6
+svn update
+svn merge ../JDK7
+-----------------
+
+ 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 -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."
+-------------------------------------------
Propchange: sis/branches/JDK7/src/site/apt/branches.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: sis/branches/JDK7/src/site/apt/branches.apt
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified: sis/branches/JDK7/src/site/apt/develop.apt
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/src/site/apt/develop.apt?rev=1394974&r1=1394973&r2=1394974&view=diff
==============================================================================
--- sis/branches/JDK7/src/site/apt/develop.apt (original)
+++ sis/branches/JDK7/src/site/apt/develop.apt Sat Oct 6 09:32:41 2012
@@ -5,6 +5,11 @@
Opening Apache SIS in an IDE
+ Different SIS branches are available depending on the target platforms (JDK6
versus JDK7,
+ or GeoAPI versions). The alternatives are listed in the
{{{./branches.html}branches page}}.
+ This section documents how to checkout the trunk for development, but the
same instructions
+ should work for any branch.
+
While the primarily SIS build system is Maven, the project provides some IDE
configuration files
for developers convenience. Before opening the project in an IDE, the source
code needs to be
downloaded from the {{{./source-repository.html}source repository}} and the
project built at
Modified: sis/branches/JDK7/src/site/apt/index.apt
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/src/site/apt/index.apt?rev=1394974&r1=1394973&r2=1394974&view=diff
==============================================================================
--- sis/branches/JDK7/src/site/apt/index.apt (original)
+++ sis/branches/JDK7/src/site/apt/index.apt Sat Oct 6 09:32:41 2012
@@ -15,20 +15,27 @@ The Apache SIS⢠library
SIS requires a Java 6 Runtime Environment.
The latest release is <<<0.2-incubating>>>.
- The current development branch is <<<0.3-geoapi3.0-SNAPSHOT>>>.
+ The version under development is <<<0.3-geoapi3.0-SNAPSHOT>>>.
* Documentation
+** User documentation
+
* {{{./download.html}Downloading binaries}}
*
{{{http://builds.apache.org/job/sis-trunk/site/apidocs/index.html}Aggregated
Javadoc}}
+ * Developer Guide (English - translation to be provided later)
({{{./book/fr.xhtml}Français}})
+
+
+** SIS developer documentation
+
* {{{./develop.html}Developing Apache SIS}}
- * {{{./code-patterns.html}Recommended code patterns}}
+ * {{{./branches.html}Branches (JDK6, JDK7, GeoAPI)}}
- * Developer Guide (English - translation to be provided later)
({{{./book/fr.xhtml}Français}})
+ * {{{./code-patterns.html}Recommended code patterns}}
Apache SIS, Apache, the Apache feather logo, and the Apache SIS project logo
are trademarks of
