sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1506178 - in /sis/site/trunk/content: branches.mdtext source.mdtext
Date Tue, 23 Jul 2013 17:41:08 GMT
Author: desruisseaux
Date: Tue Jul 23 17:41:08 2013
New Revision: 1506178

URL: http://svn.apache.org/r1506178
Log:
Ported the 'branches' page from Maven site.

Added:
    sis/site/trunk/content/branches.mdtext
      - copied, changed from r1505670, sis/branches/JDK7/src/site/apt/branches.apt
Modified:
    sis/site/trunk/content/source.mdtext

Copied: sis/site/trunk/content/branches.mdtext (from r1505670, sis/branches/JDK7/src/site/apt/branches.apt)
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/branches.mdtext?p2=sis/site/trunk/content/branches.mdtext&p1=sis/branches/JDK7/src/site/apt/branches.apt&r1=1505670&r2=1506178&rev=1506178&view=diff
==============================================================================
--- sis/branches/JDK7/src/site/apt/branches.apt [UTF-8] (original)
+++ sis/site/trunk/content/branches.mdtext [UTF-8] Tue Jul 23 17:41:08 2013
@@ -1,251 +1,242 @@
-~~
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements.  See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership.  The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License.  You may obtain a copy of the License at
-~~
-~~   http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied.  See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-~~
+Title:  Apache SIS branches
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+        or more contributor license agreements.  See the NOTICE file
+        distributed with this work for additional information
+        regarding copyright ownership.  The ASF licenses this file
+        to you under the Apache License, Version 2.0 (the
+        "License"); you may not use this file except in compliance
+        with the License.  You may obtain a copy of the License at
+        .
+          http://www.apache.org/licenses/LICENSE-2.0
+        .
+        Unless required by applicable law or agreed to in writing,
+        software distributed under the License is distributed on an
+        "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+        KIND, either express or implied.  See the License for the
+        specific language governing permissions and limitations
+        under the License.
 
-                             ------------------------------
-                                        Branches
-                             ------------------------------
 
+The [source code repository](source.html) 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.
 
-Apache SIS branches
+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 {{{./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.
+[TOC]
 
-  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
+========================
 
-* The development branches
+Developers are encouraged to select the first branch listed below, in that order, which meet
their needs.
 
-  Developers are encouraged to select the first branch listed below, in that order, which
meet
-  their needs.
 
 
+`branches/JDK7`
+---------------
 
-** <<<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 [GeoAPI 3.1-SNAPSHOT][geoapi-snapshot]
milestones
+and uses some JDK7-specific features like:
 
-  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_.
 
-    * 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_).
 
-    * Leveraging of new API (<suppressed exceptions>, <file systems>, <fork
join>).
 
 
+`branches/JDK6`
+---------------
 
-** <<<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:
 
-  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.
 
-    * <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.
+`trunk`
+-------
 
-    * <Suppressed exceptions> removed.
+The trunk is a merge of the JDK6 branch ported to the interfaces defined by the [GeoAPI 3.0.0][geoapi-stable]
stable release.
+This is the code which is built by the 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:
 
-    * Imports of <<<java.util.Objects>>> replaced by imports of <<<org.apache.sis.internal.util.Objects>>>.
+  * Usages of non-existent GeoAPI interfaces are replaced by direct usages of the
+    corresponding Apache SIS implementation.
 
-    * Other JDK7-specific features resolved on a case-by-case basis.
 
 
+Coding recommendations
+======================
 
-** <<<trunk>>>
+  The following recommendations aim to make the merges easier by reducing the extend of potential
conflicts.
 
-  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.
 
+Formatting
+----------
 
-
-* 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:
+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;
+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:
+
+    :::java
+    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();
+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.
+
+    :::java
+    { // This is a switch(String) on the JDK7 branch
+        if (string.equals("ABC")) {
+            invokeABC();
+        }
+        else if (string.equals("DEF")) {
+            invokeDEF();
+        }
     }
-}
--------------------------------------------------
 
 
 
-** Import statements
+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:
+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;
+    :::java
+    import java.io.File;
+    import java.util.List;
+    import org.apache.sis.util.ArgumentChecks;
 
-// Related to JDK7
-import java.util.Objects;
--------------------------------------------------
+    // Related to JDK7
+    import java.util.Objects;
 
 
 
-** Replacement on non-existent classes
+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.
+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
+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.
+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
+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:
+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>>>.
+  * `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`.
 
-    * <<<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.
 
-  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.
 
-  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.
+    :::bash
+    cd JDK7
+    svn update
+    cd ../JDK6
+    svn update
+    svn merge ../JDK7
 
------------------
-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:
 
-  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:
+    :::bash
+    svn resolved path/to/the/resolved/file
 
---------------------------------------
-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).
 
-  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).
+    :::bash
+    mvn clean
+    mvn compile
+    mvn test-compile
+    mvn install
 
-----------------
-mvn clean
-mvn compile
-mvn test-compile
-mvn install
-----------------
+After a successful build, commit:
 
-  After a successful build, commit:
+    :::bash
+    svn commit -m "Merge from the JDK6 branch."
 
--------------------------------------------
-svn commit -m "Merge from the JDK6 branch."
--------------------------------------------
 
 
+Declaring that some changes shall not be merged
+-----------------------------------------------
 
-** 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:
 
-  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):
 
-    * Before to apply JDK7-specific changes, merge any pending changes to the JDK6 branch.
+Commands:
 
-    * Apply the JDK7-specific changes and commit.
+    :::bash
+    cd JDK7
+    svn update
+    cd ../JDK6
+    svn update
+    svn merge --record-only ../JDK7
+    svn commit -m "Skip JDK7-specific changes."
 
-    * 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."
--------------------------------------------
+[geoapi-stable]:   http://www.geoapi.org/3.0/index.html
+[geoapi-snapshot]: http://www.geoapi.org/snapshot/index.html

Modified: sis/site/trunk/content/source.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/source.mdtext?rev=1506178&r1=1506177&r2=1506178&view=diff
==============================================================================
--- sis/site/trunk/content/source.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/source.mdtext [UTF-8] Tue Jul 23 17:41:08 2013
@@ -31,7 +31,7 @@ For fetching the source code, choose one
     :::bash
     git clone git://git.apache.org/sis.git sis
 
-The remaining of this page provides tips SIS developers.
+The remaining of this page provides tips for SIS developers.
 
 [TOC]
 



Mime
View raw message