sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1394974 - in /sis/branches/JDK7/src/site/apt: branches.apt develop.apt index.apt
Date Sat, 06 Oct 2012 09:32:41 GMT
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



Mime
View raw message