sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1834088 - in /sis/site/trunk/content: branches.mdtext index.mdtext source.mdtext
Date Fri, 22 Jun 2018 09:43:23 GMT
Author: desruisseaux
Date: Fri Jun 22 09:43:23 2018
New Revision: 1834088

Merge the branches page with the source code page.


Modified: sis/site/trunk/content/index.mdtext
--- sis/site/trunk/content/index.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/index.mdtext [UTF-8] Fri Jun 22 09:43:23 2018
@@ -72,9 +72,8 @@ Apache SIS developer documentation    {#
 Following links are for those who wish to contribute to Apache SIS:
   * [New contributor](contributor.html): background knowledge.
-  * [Source code](source.html): fetching the code, opening in an IDE, formatting.
+  * [Source code](source.html): fetching the code, choosing a branches, opening in an IDE,
   * [Build](build.html): build from the source, create the PACK200 file.
-  * [Branches](branches.html): master, geoapi-3.1, geoapi-4.0
   * [Issue tracking][JIRA]: JIRA.
   * [Release management](release-management.html) (for release managers)
   * [Web site management](site-management.html) (for release managers and site maintainers)

Modified: sis/site/trunk/content/source.mdtext
--- sis/site/trunk/content/source.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/source.mdtext [UTF-8] Fri Jun 22 09:43:23 2018
@@ -21,23 +21,96 @@ Apache SIS source code is maintained usi
 For fetching the source code, use the following commands:
-    git clone
+    git clone
 The above Git repository is mirrored on GitHub at [](
-Note that the git repository does not include the non-free data (in particular the [EPSG
geodetic dataset](epsg.html)).
+Note that the git repository does not include the non-free data, in particular the [EPSG
geodetic dataset](epsg.html).
 Those data are currently provided only on Subversion repository.
+The source code repository contains `geoapi-3.1` and `geoapi-4.0` branches in addition of
+The Apache SIS releases are created from the code on `master` only.
+However the actual development occurs on the `geoapi-4.0` branch before to be merged to `master`.
+Those branches exist in order to experiment early new API and technologies — since it may
+the library design — while keeping the releases compatible with officially released environments.
 The remaining of this page gives some guidelines about the way SIS source code is organized.
+Development branches    {#development}
+Users who want stability are encouraged to build from the `master`.
+The master depends on GeoAPI 3.0.1,
+which is the [latest GeoAPI][geoapi-stable] released by the Open Geospatial Consortium (OGC).
+Developers who want to contribute to Apache SIS are encouraged to use the `geoapi-4.0` branch
for now.
+GeoAPI 4.0 branch    {#geoapi-4.0}
+The `geoapi-4.0` branch is the recommended development branch for now.
+This branch implements the interfaces defined in GeoAPI 4.0 snapshot milestones.
+This branch uses new interfaces introduced in GeoAPI 4.0-SNAPSHOT and contains upgrades for
changes in existing GeoAPI interfaces.
+Some changes in GeoAPI 4.0-SNAPSHOT interfaces are incompatible with GeoAPI 3.0.1 interfaces.
+They are caused by changes in the underlying international standards, or by evolution of
Java technology.
+The content of this branch may be fully merged to `master` in the future, depending on new
GeoAPI releases from OGC.
+GeoAPI 3.1 branch    {#geoapi-3.1}
+The `geoapi-3.1` branch implements the interfaces defined in [GeoAPI 3.1 snapshot][geoapi-snapshot]
+It has the same content that the `geoapi-4.0` branch, excluding changes that are incompatible
with GeoAPI 3.0.1.
+Developments happen on `geoapi-4.0` and are periodically merged to `geoapi-3.1` with the
necessary modifications.
+This branch is used merely as an intermediate step between the development branch (`geoapi-4.0`)
and `master`.
+Its content may be fully merged to `master` in the future, after new GeoAPI releases from
+Master    {#master}
+The master is a merge of `geoapi-3.1` branch ported to the interfaces defined by the [GeoAPI
stable release][geoapi-stable].
+This is the code which is built by the continuous integration system and deployed on the
Maven repository.
+**Commits on master can not be removed, since `git push --force` are not allowed on this
+Commits should be pushed on above-cited development branch first,
+so they can be rearranged if needed before merge to `master`.
+### Code differences    {#differences}
+The main differences (apart version number) between `master` and `geoapi-3.1/4.0` branches
+are the modifications necessary for implementing an older version of GeoAPI interfaces.
+In particular, usages of non-released GeoAPI interfaces may be replaced
+by direct usages of the corresponding Apache SIS implementation classes.
+For security reasons and for avoiding misleading information, the following functionalities
are disabled on master for now
+(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/`, the
`ENABLED` flag is set to `false`.
+  * In `core/sis-utility/src/main/java/org/apache/sis/internal/util/`,
the `REPORT_MISSING_MODULE` flag is set to `false`.
+### Behavioral differences    {#behavior}
+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)`
+    evaluates to `true` on master but to `false` on SIS development branches.
 Opening Apache SIS in an IDE    {#ide}
 Different SIS branches are available depending on the GeoAPI versions.
-The alternatives are listed in the [branches page](branches.html).
+The alternatives are listed in [above section](#development).
 One thing to take in consideration can be summarized as below:
    * There is no need to build GeoAPI prior working on SIS master.
@@ -110,17 +183,37 @@ as below:
 Naming convention    {#naming}
-Implementations of GeoAPI interfaces usually (but not always) begin with `Abstract`, `Default`,
`Simple` or `General` prefixes.
+Classes that do not implement an interface are usually not prefixed, even if abstract.
+Classes implementing GeoAPI interfaces usually (but not always) begin with `Abstract`, `Default`,
`Simple` or `General` prefix.
   * The `Abstract` prefix is used when a class is abstract according ISO specifications —
it may or may not be be abstract in the Java sense.
   * The `General` prefix is used when an implementation is designed for use in the general
     as opposed to other implementations specialized for a fixed number of dimensions or other
   * Implementations specialized for a fixed number of dimensions are suffixed with `1D`,
`2D`, `3D` or `4D` rather than being prefixed.
-Classes that do not implement an interface are usually not prefixed, even if abstract.
+Example: `GeneralEnvelope` class is an implementation of `Envelope` interface for the multi-dimensional
+`Envelope2D` is another implementation of the same interface specialized for the two-dimensional
+Internal packages    {#internal}
+All classes in `org.apache.sis.internal` sub-packages are for SIS usage only and may change
without warning in any future release.
+Those classes are excluded from Javadoc and will not be exported by SIS Jigsaw modules.
+Those packages may be renamed after SIS upgraded to JDK 9.
+Substitution for non-existent classes    {#substitutions}
+When using a JDK 9 class that does not exist on JDK 8, define a class of the same name in
+`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 JDK9-dependent code from the development branch.
 Code formatting    {#formatting}
@@ -129,6 +222,29 @@ Apache SIS uses the standard Java conven
 The conventions listed below are guidelines. Some exceptions to those conventions can occur
but should
 be rare (see [exceptions to coding conventions](#tabular-formatting)).
+For making merges between branches easier, 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    {#imports}
+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:
+    :::java
+    import;
+    import java.util.List;
+    import org.opengis.metadata.Metadata;
+    // Branch-specific imports
+    import org.opengis.feature.Feature;
 Spaces and line length    {#spaces}
@@ -297,3 +413,5 @@ Note that a [JavaScript display engine][

View raw message